Valet|Docs
Sign up

CLI: Agents

Create an agent

valet agents create [name] [--org <org>] [--from <source>] [--path <dir>] \
  [--attach-connector <name>] [--attach-channel <name>] [--no-wait]

Creates the agent, links the directory, and deploys v1. The source must contain a SOUL.md file. Name is optional; the server generates one if omitted. After deploying, the command waits for the agent runtime to become ready. Use --no-wait to skip the readiness check.

Sources

The --from flag controls where the agent definition comes from:

  • Current directory (default) — Uses the SOUL.md in the current directory.
  • Local path — --from . or --from ./my-agent for a specific local directory.
  • Git repository — --from github.com/user/repo clones and deploys from a remote repo.
  • Catalog — --from catalog:name creates from a Valet-curated agent template.

When --from points to a Git URL or catalog reference, the repo is cloned and the project files are scaffolded to a local directory (default ./<name>/, override with --path).

# Create from a catalog template
valet agents create my-reviewer --from catalog:code-reviewer --org acme

Manifest Slack installation

When the source contains a valet.yaml manifest, it is validated before proceeding. If the manifest declares a channel with catalog: slack, the CLI checks the org's Slack connection, prompts for a bot name, and creates the Slack channel inline:

$ valet agents create support-bot --from catalog:slack-support --org acme
Fetching catalog:slack-support... done
Creating agent... done, support-bot agent in acme org
Checking Slack connection... connected (My Workspace)
Bot name [support-bot]: support-bot
Creating Slack channel... done, support-bot-slack
Deploying support-bot agent in acme org... done, v1
Scaffolding ./support-bot... done
Linking directory... done
Waiting for agent to start... done

If the org has no connected Slack workspace, the command exits with an error directing you to connect Slack first with valet channels create slack --org <org>.

Attaching resources at creation

Use --attach-connector and --attach-channel (both repeatable) to wire org-scoped resources to the agent at creation time:

valet agents create my-bot --org acme \
  --attach-connector github \
  --attach-channel gh-webhook

Organization ownership

Use --org to assign the agent to a specific organization. When omitted, the default org is used. The default org is set automatically when you create or join an org.

Scaffold a new agent project

valet new <name> [--dir <path>]

Creates a new agent project directory without deploying. The scaffolded directory contains SOUL.md, AGENTS.md, CLAUDE.md, a placeholder valet.yaml, and the skills/ and channels/ subdirectories. Edit SOUL.md to define your agent, fill in the manifest's display_name/description/category, then run valet agents create to deploy it.

$ valet new my-agent
Created agent project my-agent

  my-agent/
    SOUL.md        Agent personality and behavior
    AGENTS.md      Conventions for coding agents
    CLAUDE.md      Points Claude Code at AGENTS.md
    valet.yaml     Manifest describing connectors and channels
    skills/        Custom skills (add .md files)
    channels/      Channel prompts (add .md files)

Link a directory to an existing agent

valet agents link <name> [--org <org>] [--force]

Creates .valet/config.json so subsequent commands auto-detect the agent. Pass --org when you belong to more than one org. Use --force to replace an existing link.

Deploy a new release

After editing SOUL.md or other files, deploy the changes:

valet deploy [-a <name>] [--org <org>] [--no-wait] [--force] [--allow-unsatisfied]

Pushes the agent bundle to a fresh draft branch, promotes the draft to main, and activates the release. The agent is determined by the -a/--agent flag or the linked agent from the current directory. After deploying, the command waits for the agent runtime to become ready; use --no-wait to return immediately after the release is activated.

  • If the agent already has an open draft (e.g. from an Architect session in the dashboard), deploy errors out with the existing draft's id. Discard it with valet drafts discard <id>, or pass --force to drop it and proceed.
  • If the local source is identical to the agent's main branch and a release has already deployed it, deploy exits 0 without re-releasing. Pass --force to rebuild unchanged source anyway.
  • If the manifest declares integrations or channels that aren't attached yet, deploy stops and lists what's missing. Pass --allow-unsatisfied to deploy anyway — the agent runs without them until they're attached. A manifest that fails to parse is always a hard error.
$ valet deploy --agent my-agent
Opening draft for my-agent agent in acme org... done
Pushing source... done
Publishing draft... done
Deploying my-agent agent in acme org... done, v3
Waiting for agent to start... done

List agents

valet agents [--org <name>]

Lists agents in the default org. Use --org (or -o) to list agents in a different organization.

Agent info

valet agents info [name] [-a <agent>] [--org <org>]

Shows the agent's org, current release, process state, channels, integrations, and effective environment. Environment rows show each env var's kind and scope; plain values are shown inline, secret values are masked. The agent is determined by the positional argument, the -a/--agent flag, or the linked agent in the current directory.

$ valet agents info my-agent
=== Agent: my-agent (acme org)
  org:        acme-corp
  release:    v3
  process:    up for 3h22m
  channels:   slack-channel, support-webhook
  connectors: github-mcp, linear-mcp
  environment:
    GITHUB_TOKEN  secret  ******     agent (overrides org)
    REGION        plain   us-east-1  org (inherited)

Rename an agent

valet agents rename <new-name> [-a <agent>] [--org <org>]

The new name follows the same validation as agents create: it must be a DNS label and not a reserved word. Renaming is safe at any point in an agent's lifecycle — webhook URLs are keyed by channel UUID, Slack and runtime routing are keyed by agent UUID, and the dashboard URL slug redirects on rename. If a .valet/config.json above the current directory points at the renamed agent, it is updated in place to the new name.

# Rename the linked agent in the current directory
valet agents rename better-name

# Rename a specific agent in an org
valet agents rename better-name --agent my-agent --org acme

Scale an agent

valet ps scale agent=<value> [-a <agent>] [--org <org>]

For an agent, pass a single agent=<value> pair. The right side of = is either a model ID, a process count, or model:count. Changing the model preserves the current count; changing the count preserves the current model. Today an agent's count must be 0 or 1. Scaling bounces affected containers so the new settings take effect on restart.

Available agent models:

  • claude-sonnet-5
  • gpt-5.6-sol
  • gpt-5.6-terra
  • gpt-5.6-luna
  • glm-5.3
  • glm-5.3-flash

The server enforces the authoritative allowlist. Run valet ps scale --help to see the current list of supported models.

# Switch the linked agent to a different model
valet ps scale agent=gpt-5.6-terra

# Stop the agent (scale to zero)
valet ps scale agent=0

Destroy an agent

valet agents destroy <name> [--org <org>]

Permanently removes the agent and all its releases. The agent name is required. Cannot be undone.