> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remotemux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects

> How RemoteMux uses the current directory, local state, and project-level config.

In RemoteMux, a project starts with the local directory you are standing in.

## The Current Directory Is The Selector

RemoteMux is directory-first. When you run `rmux env new`, RemoteMux stores a local binding for that directory. Later, re-entering the same folder lets RemoteMux find the right environment automatically.

That is why many "not found" problems are really directory mismatch problems.

## What Lives Locally

| Path                 | What it stores                                        |
| -------------------- | ----------------------------------------------------- |
| `./.rmux.toml`       | Project-level RemoteMux config for this directory.    |
| `./.rmux/state.json` | The local binding to the remote environment.          |
| Your source tree     | The code RemoteMux syncs into the remote environment. |

## The Binding Model

* One project directory maps to one RemoteMux environment.
* RemoteMux loads the binding from `.rmux/state.json`.
* Commands like `rmux workspace attach` and `rmux env status` work because the directory tells RemoteMux which environment to target.

If you need to act on an environment from another directory, use `rmux env list` and target it by name or ID.

## Directory Project vs Hosted Project

RemoteMux uses the word "project" in two different ways:

* The local project is the directory on disk that owns `.rmux.toml` and `.rmux/state.json`.
* The hosted project is the organization-scoped resource in the control plane that owns environments, service tokens, and usage on hosted backends.

On hosted backends, you can pin the active hosted scope in config:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
organizationId = "org_123"
projectId = "proj_123"
```

That scope is then used by commands such as `rmux env new`, `rmux usage`, and `rmux token create` unless you override it with explicit flags.