Agents & sessions

Message the agent

Sends a message to the project's agent — the same agent the dashboard workspace chats with — and returns its reply. The CLI and SDK ensure a session is running first and wait for the reply.

spaceboy agent message "Add dark mode" --project prj_...
spaceboy agent message "..." --project prj_... --track   # mirror as a tracked task

Commands target the project's sandbox environment by default; pass --env <environmentId> or --mode development|production to target another environment.

Follow the conversation

Read a conversation's messages, or tail the project's latest one live.

spaceboy agent tail --project prj_...   # or --conversation <id>

Manage workspace sessions

The workspace session is the running machine the agent works in. Start it, check it, stop it.

spaceboy session start --project prj_...
spaceboy session status --project prj_...
spaceboy session stop --project prj_...

Share a live preview

While a session runs, mint a shareable read-only URL to the live app — no Spaceboy login needed to view it. Links expire on their own.

spaceboy preview url --project prj_... --expires 30

Ask about your organization

The agent answers questions about your whole organization — projects, usage, activity — and proposes actions it can take, which you confirm explicitly.

spaceboy ask "Which projects deployed this week?"
spaceboy confirm <actionId>          # approve a proposed action
spaceboy confirm <actionId> --deny

Inspect agent runs

Every metered agent run — status, duration, model, tokens, cost — with full transcripts for diagnosis.

spaceboy runs --project prj_... --status FAILED
spaceboy runs show <runId>
spaceboy runs transcript <runId>