# Remote Control & Agents

> Source: https://parallelworks.com/docs/ai/code/remote-control

# Remote Control & Agents

`pw code` sessions are hosted by a background daemon on your machine, not by the terminal you started them in. That is what lets a session keep working after you quit, lets you browse and manage every session from one list, reach sessions on another machine with `pw code attach`, and view and drive a session from the web app with remote control.

## Remote Control

Remote control makes a session viewable and drivable from the web app's **Agents** page. Turn it on from inside a session:

```text
/rc
```

`/rc` (or `/remote-control`) accepts `on` (the default), `off`, and `status`. It answers with the session's address, `https://<platform-host>/agents?session=<session-id>`, and the status line shows a `/rc` badge while it is on. To start a session with remote control already on, pass `--remote`:

```bash
pw code --remote
```

From the web app you can follow the conversation as it streams, send prompts, answer approval prompts, and interrupt the agent. The session itself keeps running on your machine, and its transcript stays there.

`/rc off` disconnects remote access to the session. Work that was already accepted keeps running.

### Remote Control Settings

These settings live in your user settings file, `~/.config/pw/code.json`, under `remoteControl`. A workspace's settings files cannot set them, so a repository can never open your machine to remote drive. The first three are rows in `/settings`.

| Key | `/settings` row | Default | Description |
| --- | --- | --- | --- |
| `newSessions` | **Remote control for new sessions** | `false` | Start every new session with remote control on. `--remote=false` overrides it for one launch. |
| `start` | **Allow remote session start** | `false` | Let the web app start new sessions on this machine. |
| `maxPermissionMode` | **Remote permission ceiling** | `accept-edits` | The highest [permission mode](/docs/ai/code/permissions) a remote turn may run at: `read-only`, `plan`, `accept-edits`, or `bypass-permissions`. |
| `selfConnect` | (none) | `true` | Let the daemon connect this machine to the platform itself while anything here is open to remote control. Set `false` to make the machine reachable only through a `pw` agent running on it. |

```json
{
  "remoteControl": {
    "newSessions": true,
    "maxPermissionMode": "read-only"
  }
}
```

### What Remote Turns May Do

A prompt sent from the web app runs with tighter rules than one typed in your terminal:

- **The ceiling applies.** The turn runs at the session's permission mode, lowered to the remote permission ceiling when the mode is higher.
- **Your standing approvals do not apply.** [Allow rules](/docs/ai/code/permissions#allow-rules), directories you approved earlier, and skill tool grants do not pre-approve anything on a remote turn, so the action goes through an approval prompt instead.
- **Configuration files always ask.** Writes to the workspace's `.agents/` directory or `.mcp.json` prompt for approval even in `bypass-permissions` mode.
- **Skills and commands that run shell commands while expanding** are refused when invoked remotely.

A session that runs above the ceiling, for example in `bypass-permissions` with the default ceiling, can still be watched and interrupted from the web app, but remote clients cannot send it prompts or approve its actions. `/rc status` says so.

## The Background Daemon

The first `pw code` you run starts a per-user daemon in the background. It hosts every session on this machine, interactive and [one-shot](/docs/ai/code/non-interactive) alike, and each terminal running `pw code` is a client of it.

- **Quitting detaches.** A running turn finishes in the background, and the exit message prints the command to reconnect. Resume the session to pick it back up.
- **It keeps running until stopped.** The daemon does not exit when idle. Scripts and CI jobs that run `pw code -p` can stop it afterwards with `pw code daemon stop`.
- **Upgrades are picked up.** After you update `pw`, the outdated daemon is replaced automatically the next time `pw code` starts while it hosts no live sessions.
- **Sign-ins are picked up.** After `pw auth` in another shell, new sessions use the new credentials without a restart.

Manage it with the `pw code daemon` commands:

```bash
# Show the daemon's pid, version, live session count, and remote control policy
pw code daemon status

# Start it in the background (pw code does this automatically)
pw code daemon start

# Stop it: running turns end and every session closes; sessions stay saved and resumable
pw code daemon stop
```

The daemon's socket and log live under `~/.local/state/pw` (or `$XDG_STATE_HOME/pw`), named after the host so that machines sharing a home directory each run their own: `code-<host>.sock` and `code-daemon-<host>.log`. A log that has grown past 8 MB is moved to `code-daemon-<host>.log.1` the next time the daemon starts. See [pw code daemon](/docs/cli/pw/code/daemon) for the command reference.

## Attaching to Another Machine

`pw code attach` connects your terminal to the sessions on another resource over SSH. The sessions run on the resource, with its files, tools, and session store; your terminal only shows and steers them.

```bash
# Browse the resource's sessions and pick one to resume
pw code attach my-cluster

# Attach to one session directly
pw code attach my-cluster/20260819-101500-ab12cd34

# Start a new session in a workspace on the resource
pw code attach -w /home/user/project -m org:openai/gpt-5.2 --allocation my-allocation my-cluster
```

You need SSH access to the resource, as for `pw ssh`, and a version of `pw` on it that includes the daemon. The daemon starts there automatically. For a new session, `-w` must be an absolute path on the resource, and `-m`, `--effort`, `--allocation`, and `--permission-mode` work as they do for `pw code`. Inside an attached session, `/auth` asks for a pasted API key or token, since the resource keeps its own sign-in. See [pw code attach](/docs/cli/pw/code/attach) for the command reference.

## The Agents List

The agents list shows every `pw code` session on this machine with its live status, grouped and filterable, with a details pane for the selected session. Open it with `/agents`, with <kbd>←</kbd> at an empty prompt, or from your shell:

```bash
# Open the agents list
pw agents

# Live sessions plus recent history, as text or JSON
pw agents -o text
pw agents -o json
```

Tabs across the top filter by status, each with a count: **All**, **Needs you** (waiting for an approval or an answer), **Working**, **Ready**, and **Inactive**. Sessions live on another host that shares your home directory are marked as such. Pinned sessions are listed first.

| Key | Action |
| --- | --- |
| <kbd>↑</kbd>/<kbd>↓</kbd>, <kbd>PgUp</kbd>/<kbd>PgDn</kbd> | Move through the list. |
| <kbd>Enter</kbd> or <kbd>→</kbd> | Open the selected session. |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Cycle the status filter. |
| <kbd>g</kbd> | Change grouping: by project, status, or model. |
| <kbd>/</kbd> or <kbd>F3</kbd> | Search. |
| <kbd>n</kbd> | Start a new session. |
| <kbd>w</kbd> | Start a new session in a new git worktree: a detached checkout of the repository's default branch, under `~/.local/state/pw/code-worktrees`. |
| <kbd>o</kbd> | Open the [session picker](/docs/ai/code/sessions#the-session-picker) across all saved sessions. |
| <kbd>f</kbd> | Fork the selected session into a new one with a copy of its history, and open it. |
| <kbd>r</kbd> | Rename the selected session. |
| <kbd>p</kbd> | Pin or unpin it. |
| <kbd>x</kbd> | Stop its running turn. |
| <kbd>a</kbd> | Archive it and its subagents (asks first). |
| <kbd>h</kbd> | Hide it from the list for now. |
| <kbd>Backspace</kbd> | Permanently delete it and its subagents (asks first). |
| <kbd>?</kbd> | Show the keys. |
| <kbd>Esc</kbd> | Go back. |

The grouping you choose is saved as the `agentsGrouping` setting (`project`, `status`, or `model`). To change the keys, set `agentsKeymap` in `~/.config/pw/code.json` to a map from action to keys. The actions are `help`, `open`, `filter_next`, `filter_prev`, `group`, `search`, `new`, `new_worktree`, `resume`, `fork`, `rename`, `toggle_pin`, `stop`, `archive`, `hide`, and `delete`; `open_agents` adds keys that open the list from the chat. An action given an empty list is unbound.

```json
{
  "agentsGrouping": "status",
  "agentsKeymap": {
    "delete": ["ctrl+x"],
    "open_agents": ["ctrl+a"]
  }
}
```

See [pw agents](/docs/cli/pw/agents) for the command reference.

## Related Documentation

- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Sessions & Resume](/docs/ai/code/sessions): How sessions are saved and resumed
- [Permissions](/docs/ai/code/permissions): Permission modes and allow rules
- [Settings](/docs/ai/code/settings): The settings files and `/settings` menu
- [Non-Interactive Mode](/docs/ai/code/non-interactive): One-shot runs and the daemon in CI
- [pw code daemon](/docs/cli/pw/code/daemon): Daemon command reference
- [pw code attach](/docs/cli/pw/code/attach): Attach command reference
- [pw agents](/docs/cli/pw/agents): Agents list command reference