Hosted Dev Agent

Every Buildspace app can run an always-on hosted dev workspace with an embedded AI coding agent. The agent lives in the same container as your dev server, so it can read, edit, and run commands against your live codebase — and your app hot-reloads as it works.

The buildspace agent commands let you check the workspace status, open it in a browser, configure which AI provider it runs with, and review or push the changes it makes — all without leaving the terminal.

The hosted agent is dev-only. Changes it makes land on the buildspace/dev branch, which you can later promote to production.

Prerequisites

Enable hosting for the dev environment first — this provisions the workspace and agent:

buildspace app hosting enable --env dev

Then point the agent at an AI provider with a key of your own (see Configure the AI provider).

Check Status

buildspace agent status
buildspace agent status --json

Shows the workspace status, the agent URL, the tracked git branch (buildspace/dev), and whether an AI provider key is configured.

App: My App (my-app)
  status:   active
  url:      https://my-app-agent.devapps.buildspace.studio
  branch:   buildspace/dev
  provider: configured (anthropic)

If you see Hosted dev agent is not enabled, run buildspace app hosting enable first.

Options

Open the Workspace

buildspace agent open
buildspace agent open --no-open

Opens the agent workspace in your browser. Access is gated by your Buildspace login — only the app owner can open it; there is no separate username or password. Use --no-open to print the URL instead of launching a browser (useful in scripts or remote shells).

Options

Configure the AI Provider

The agent runs with an AI provider key that you supply. Only one provider can be active at a time — setting a new one revokes the others.

buildspace agent key set --provider anthropic --key sk-ant-...

To keep the key out of your shell history, omit --key and pipe it via stdin:

cat key.txt | buildspace agent key set --provider openai

After setting a key, restart the workspace for the agent to pick it up.

Supported providers

Options

Review Changes

The agent works in the live workspace without committing. Use inspect to see what it has changed before you accept anything.

buildspace agent inspect
buildspace agent inspect --json

App: My App (my-app)
  branch:  buildspace/dev
  clean:   false
  2 changed file(s):
    M  app/page.tsx
    A  app/api/auth/route.ts

Options

Accept Changes

Commit and push the workspace's pending changes to the tracked buildspace/dev branch:

buildspace agent accept
buildspace agent accept --message "Add auth flow"

If you omit --message, a default commit message is used. Once pushed, the changes are ready to promote to production. If the workspace is already clean, nothing is committed.

Options

Reset the Workspace

Discard all pending changes and reset the workspace to match the tracked branch:

buildspace agent reset

This performs a hard reset to origin/buildspace/dev and removes untracked files. Use it to recover when the workspace gets into a bad state. This cannot be undone — accept anything you want to keep first.

Options

Typical Workflow

# One-time setup
buildspace app hosting enable --env dev
buildspace agent key set --provider anthropic --key sk-ant-...

# Open the agent and give it a task in the browser
buildspace agent open

# Back in your terminal, review what it changed
buildspace agent inspect

# Accept the changes onto buildspace/dev
buildspace agent accept --message "Add auth flow"

# ...or throw them away and start over
buildspace agent reset

The inspect, accept, and reset commands are scriptable with --json and stable exit codes, so you can drive the hosted agent from CI or another agent. See JSON Output for the error format.