Use this setup when fp runs somewhere that cannot access the local fp store,
such as a cloud coding environment, a CI job, or a fresh remote checkout. If
the agent runs on your machine, you do not need `FP_REMOTE` or `FP_TOKEN`.

In remote mode, issue and comment commands talk to a shared fp project over
HTTPS. There is no local database to copy into the remote environment.

## Link the project

Run this once from a local checkout:

```bash
fp auth login
fp project link
```

Choose or create a project when prompted. `fp project link` writes
`.fp/remote.toml` and makes that file available to Git:

```bash
git add .fp/remote.toml .gitignore
git commit -m "Configure fp remote project"
```

The file contains the workspace slug, project ID, server URL, and display
prefix. It does not contain a token.

If the project was linked before `remote.toml` was introduced, create it with:

```bash
fp project remote stamp
```

Run `fp project remote` to check the configured project.

## Create an agent token

A workspace admin or owner can create a dedicated agent and token:

```bash
fp workspace agent create \
  --workspace <workspace-slug> \
  --name <agent-name> \
  --role member \
  --expires-in 30
```

Workspace agent authentication must be enabled for the workspace. fp displays
the token once, so copy it directly to the secret store used by the remote
environment.

A personal access token also works, but a dedicated agent token is easier to
revoke and does not use a person's identity.

## Configure the remote environment

Set both variables in the cloud environment or CI job:

```bash
export FP_REMOTE=rest-api
export FP_TOKEN=<token>
```

Do not add `FP_TOKEN` to `.fp/remote.toml`, an agent instruction file, or any
other file in the repository.

## Use fp from the cloud environment

After cloning the repository and installing fp, use the familiar issue and
comment commands:

```bash
fp issue list
fp issue show FP-abcd
fp issue create --title "Investigate failing build"
fp issue update --status in-progress FP-abcd
fp comment FP-abcd "Reproduced in the cloud sandbox"
fp search "failing build"
```

REST mode supports these commands:

- `fp issue list`, `show`, `create`, `update`, `delete`, and `assign`
- `fp comment add`, `list`, `update`, and `delete`
- `fp search`
- `fp attach`

`fp tree`, `fp context`, brainstorms, and project sync still require local fp
state. In REST mode, fp reports that these commands are unsupported.

## Configure identity without committing a file

If the checkout does not include `.fp/remote.toml`, set the project identity in
the environment:

```bash
export FP_REMOTE=rest-api
export FP_WORKSPACE=<workspace-slug>
export FP_PROJECT_ID=<project-id>
export FP_SERVER_URL=https://app.fp.dev
export FP_TOKEN=<token>
```

These values override `.fp/remote.toml`. Always set `FP_SERVER_URL` explicitly
when using a server other than `https://app.fp.dev`.

## Return to local mode

Unset the remote variables to use the local fp store again:

```bash
unset FP_REMOTE
unset FP_TOKEN
```