Deploy with your AI

Guv is built to be operated by AI agents as well as people. Your agent uses the same API as the dashboard, but with a token you control: what it can touch, how much it can spend, and when it has to ask you first.

Connect your agent

The quickest way is to let the CLI set everything up. It installs a use-guv skill (or rules file) that teaches your agent how to deploy, read logs, set secrets without echoing them, and handle approval requests:

guv setup agent

Or connect any MCP client to the remote server yourself. It uses OAuth, so you approve the connection in your browser and see exactly which scopes it asks for:

claude mcp add --transport http guv https://mcp.guv.dev

For a local server that uses your CLI sign-in, point your client at guv mcp (stdio).

What the MCP server offers

A small set of task-level tools rather than one tool per endpoint:

Tool	What it does
project_status	Health, recent deploys, errors, spend and safety grade in one call.
deploy	Deploys a service, with plan and apply modes.
logs_query, logs_tail	Searches logs and follows them for a bounded time.
set_secret	Sets a secret. Write-only: it can never read one back.
list_variables	Lists variable and secret names and metadata, never secret values.
manage_domain	Adds and verifies custom domains.
manage_database	Creates databases, makes branches, returns connection details.
diagnose	Explains a failing deploy and suggests the fix.
apply_manifest	Validates, plans and applies guv.yaml.
request_approval, get_operation	Asks a human and follows long-running work.

Agent tokens

An agent token is created by a person, and says exactly what the agent may do:

name: claude-code-on-stewart-laptop
scopes: [projects:read, deploy:preview, deploy:staging, logs:read, secrets:write-only, db:branch]
environments: [preview, staging]        # production is excluded
budget: { spend_increase_per_day: 10GBP }
expires: 30d
approval_channel: push+email

The dashboard describes every token in plain sentences, for example: “Can deploy to staging and previews. Cannot touch production.”

Approvals

When an agent asks for something outside its token, such as a production deploy, Guv does not just refuse. It stores the request and asks you:

1. The API answers 403 with the code approval_required and an approval_url. The CLI exits with code 4.
2. You get a push notification and an email. You review the plan, including the cost change, and approve with your passkey.
3. Guv runs the stored request. The agent waits with guv approvals wait <id> and sees the result.

The agent never sees a credential. It only learns whether you said yes.

Some actions always need a human, whatever the token says:

• deleting any database or volume;
• restoring over production;
• turning off backups;
• making a database reachable from the internet;
• raising a spend cap.

Keeping agents honest

• Every action is labelled with the agent that did it, for example via agent: claude-code-on-stewart-laptop, and appears in the activity feed.
• You can replay an agent’s session: the sequence of calls and the plans it made.
• Tool results that contain your logs or web content are marked as untrusted, so a well-behaved agent treats them as data, never as instructions. This is a defence against prompt injection.
• Tokens are recognisable by their guv_agt_ prefix and registered with secret scanners, so a leaked token is caught quickly.