# Agent home recipe

URL: https://briq.cloud/cookbook/agent-home

> One person's computer for agent CLIs: Claude Code, Codex, Copilot CLI, Cursor, Grok Build and Mistral Vibe, unmodified and pinned. The person signs in with each vendor's own flow in the terminal at the private URL; sign-ins stay on its volume, which is never forked or backed up. Drive sessions with briq_exec (claude -p, codex exec); heavy work goes to a sandbox briq.

Tags: sandbox, agents

Guide:

- [Run your agent CLIs in the cloud](https://briq.cloud/docs/guides/run-agent-clis-in-the-cloud.md): Claude Code, Codex, Copilot CLI, Cursor, Grok Build and Mistral Vibe on a computer of your own, signed in with your own plans, working while your laptop is closed.

## Run it

briq.yaml:

```yaml
stack: app
services:
  home:
    recipe: agent-home
    # its defaults, each a field you can set:
    # image: ghcr.io/briq-cloud/agent-home:latest
    # size: small
    # volume: { gb: 5 }
```

MCP:

```ts
briq_run({ recipe: "agent-home", wait: true })
```

REST:

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "agent-home",
    "wait": true
  }'
# → { "briqs": [{ "id": "bq_…", … }], "outputs": { "HOME_HOST": "…" }, … }

# ... when done, for each briq id
curl -X DELETE https://api.briq.cloud/v1/briqs/<id> \
  -H "Authorization: Bearer $BRIQ_API_KEY"
```

## Fields

Set them beside `recipe`, in briq_run or a briq.yaml service, as a GitHub Actions service.

| Name | Type | Options | Default | What it does |
| --- | --- | --- | --- | --- |
| `image` | string | — | "ghcr.io/briq-cloud/agent-home:latest" | A date tag of the same image (ghcr.io/briq-cloud/agent-home:2026-10-27) to keep the CLI versions |
| `env` | record | { key: string \| { secret, value?, scope?, hosts?, locations? } } | {} | Added to the home's environment. API-key mode for a vendor: its team secret, { secret: "ANTHROPIC_API_KEY", scope: "team" }, which the credential gateway fills on the way to the vendor. ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, OPENAI_API_KEY, CODEX_API_KEY, COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN, CURSOR_API_KEY, XAI_API_KEY, MISTRAL_API_KEY are taken only that way: any other value replaces the person's subscription. A base URL, a proxy or CA variable, PATH and HOME are refused |
| `size` | enum | nano, small, medium, large | "small" | small for one or two CLI sessions at once; medium for three |
| `volume` | object | { gb? } | {"gb":5} | The volume at /work, sign-ins and files: { gb } |

## Outputs

Returned by `briq_run` once the stack is healthy. Hosts resolve inside your team network; secrets are generated per run.

| Output | Value |
| --- | --- |
| `HOME_HOST` | `home.<stack>.internal` |
| `WORKDIR` | `/work` |
| `LOGINS` | `/work/.logins` |

## What it runs

| Briq | Image | Ports | Size | Volume |
| --- | --- | --- | --- | --- |
| home | `ghcr.io/briq-cloud/agent-home:latest` | 8080 | small | 5 GB at /work |

## When to use it

* One person wants Claude Code, Codex, Copilot CLI, Cursor, Grok Build or Mistral Vibe running in
  the cloud, on their own subscription.
* An app gives each of its users a computer for their agents: one home per person.
* Sessions that go on while the person's laptop is closed.

```text
briq_run({ recipe: "agent-home", stack: "home-ana", expose: "private" })
```

Step by step: [Run your agent CLIs in the cloud](https://briq.cloud/docs/guides/run-agent-clis-in-the-cloud).

## Sign in

Open the home's URL: it is a terminal. Run the vendor's own sign-in once per CLI, and follow
what it prints.

| CLI          | Command                         | What you do                                                                                       |
| ------------ | ------------------------------- | ------------------------------------------------------------------------------------------------- |
| Claude Code  | `claude auth login`             | Open the link, sign in, paste the code back                                                       |
| Codex        | `codex login --device-auth`     | Turn on device code sign-in in ChatGPT's security settings, then open the link and enter the code |
| Copilot CLI  | `copilot login --device-code`   | Open the link, enter the code, answer yes to storing the token in a file                          |
| Cursor       | `NO_OPEN_BROWSER=1 agent login` | Open the link, sign in                                                                            |
| Grok Build   | `grok login --device-auth`      | Open the link, enter the code                                                                     |
| Mistral Vibe | `vibe --setup`                  | Pick the browser sign-in, open the link it prints, sign in                                        |

Each sign-in stays in `/work/.logins/<cli>` on the home's volume. It lasts through sleep,
restarts and a newer image.

## Tips

* **Sessions from outside**: `briq_exec` with `async: true`,
  `["claude", "-p", "…", "--output-format", "stream-json"]` or `["codex", "exec", "--json", "…"]`,
  then `briq_exec_result` ([Run a long command](https://briq.cloud/docs/guides/run-a-long-command)).
* **One Codex at a time per home**: two Codex processes that refresh the same sign-in sign each
  other out. Run Codex threads in one `codex app-server`.
* **Heavy work in a sandbox**: a test suite, a build, a browser. Start a
  [sandbox](https://briq.cloud/cookbook/sandbox) briq, never a fork: no sign-in reaches it.
* **Private URL only**: the terminal is a root shell next to every sign-in, so `expose: "public"`
  and a TCP endpoint are refused.
* **Your team only**: anyone with a key to the team can read the sign-ins with `briq_exec`. Keep a
  home in your personal team.
* **No base URL, no proxy**: `env` refuses the variables that would send the CLIs' requests
  elsewhere (`ANTHROPIC_BASE_URL`, `HTTPS_PROXY`, a CA bundle, `PATH`).
* **No fork, no backup**: the volume is never copied, so a home cannot be forked. Keep work that
  matters in git.
* **API key instead of a plan**: add the key as a team secret, then pass
  `{ secret: "ANTHROPIC_API_KEY", scope: "team" }` in `env`. The home holds a placeholder; the
  credential gateway sends the key to the vendor. A plain value is refused: it replaces the plan.
* **Versions are the image's**: the CLIs never update themselves; the image is built again each
  week. Pin a date tag, `image: "ghcr.io/briq-cloud/agent-home:2026-10-27"`, to keep them. Every
  version: [REFERENCE.md](https://github.com/briq-cloud/agent-home/blob/main/REFERENCE.md).
* **`small` for one or two sessions**; `medium` for three.
* **Asleep after 30 minutes without use**: a command sent with `briq_exec` wakes it.