Assist agents with agent-cli

rac is the command name for Redgold's agent CLI. In a managed Redgold environment, a trusted agent or operator can use it to inspect capacity, start another agent, send bounded work through a ticket, observe progress, and stop work that should end. This is an allowed agent-assistance path when the caller has an assigned environment and the corresponding fleet permissions.

The fleet workflows below require an assigned environment. For tools on your own machine, start with agent tools setup and the RAC command guide: search, browsers, memory, data and remote builds use their respective service permissions. An account API key alone does not grant fleet administration. Customer applications can discover declared remote operations through MCP; the assigned-agent REST guide describes the separately provisioned agent-control boundary.

Use account commands from your computer

Account commands work from a laptop over HTTPS with REDGOLD_API_KEY, or the api_key saved in ~/.redgold/credentials.toml. This includes conversations, notes and entities, data queries, sharing, usage, installed-app records and browser requests. rci uses the same saved credential for its authorized remote build and CI operations. Server permissions still determine which repositories, workspaces and operations the account can access.

REDGOLD_API selects the account's API realm; the default is https://api.redgold.ai. Set it only when your operator gives you a different API host. This selection is independent of the model provider: using another model gateway does not require Kubernetes credentials or a managed agent pod. Explicit command URLs and credentials retain their precedence.

For example:

rac des datasets
rac des sql 'select * from my_dataset limit 10'
rac des usage week
rac app list
rac browse https://example.com --quote
rac summarize 'A short description of this project'
rac complete 'Explain this code' --model claude-haiku-4-5-20251001

rac browse uses a prepaid API session by default, with direct network egress, a $0.05 spending ceiling, at most 5 MB of traffic and a 60-second lifetime. Use --quote to inspect pricing, --max-cost-usd to set the ceiling, and --egress oxylabs --geo us to select residential egress. HTML, JSON and screenshots use that same session. A direct internal service is an explicit --service-url or CAMOUFOX_SERVICE_URL override. Custom proxy endpoints and credentials on the client require that explicit direct-service path; hosted custom egress uses server configuration.

Data commands use the authenticated native dataflow API. rac des query --explain prints the submitted query plan without executing a read. Registry commands use authenticated API routes and retain their existing signing-key, namespace and installation-administrator requirements.

Code-index reads and dataset imports use the same account API and require access to the selected datasets. Import cursors bind to the account, workspace, endpoint and input; switching one requires a separate cursor. Signing-key commands also use HTTPS and retain their server-side enrollment requirements.

rac summarize and rac complete use the metered model API by default. Set RAC_COMPLETION_MODEL or use complete --model to select a model. The default is Claude Haiku 4.5; model access and account credits still apply. Managed completion backends and summarizer rollups require an explicit SUMMARIZER_URL. The REPL client uses the selected account API with the same caller and workspace for HTTP and WebSocket requests. Its deployment must provide an authorized REPL service; the shared development REPL is outside the public self-service contract.

Remote Cargo builds use HTTPS too. Public laptop keys select the isolated, prepaid /v1/build/jobs API for build, check and test; use --remote api to select it explicitly. The current service builds published GitHub revisions and returns results and logs. Inspect a returned job with rac cargo status <job-id>, logs <job-id> or cancel <job-id>. It currently does not upload local edits, fetch private repositories or download build artifacts. Use --local for local Cargo or select an explicitly provisioned source-tree builder for those capabilities. Development fleet builds retain their existing repository and artifact permissions; public keys never default to that fleet.

Fleet administration, deployment publication and commands that explicitly manage Kubernetes or SSH resources require their corresponding provisioned permissions. An account key does not grant fleet access. The managed-onboarding /v1/agents/* routes remain outside the self-service public API contract; see the V1 route reference.

Inspect available agents

rac fleet status

The status view identifies running slots, their current state, branch, context usage, and last activity. Use it before assigning work so two coordinators do not target the same slot.

Start an assisting agent

Allocate a slot from an allowed group and give it one bounded task. Replace GROUP with a group name your environment operator assigned:

rac agent spawn --group GROUP \
  --prompt "Review the API documentation examples and report inaccurate requests. Do not edit files."

The command returns the allocated slot and a command identifier. Keep the prompt scoped to an independently verifiable result. The parent agent remains responsible for reconciling the answer with other work and verifying any combined change.

When a specific assigned slot is appropriate, pass its name in place of SLOT:

rac agent spawn SLOT \
  --prompt "Run the focused documentation contract test and report the failing assertion."

Slot names and group names come from the environment operator. A caller cannot use this command to acquire a repository or tenant outside its configured scope.

Drive work from a ticket

Tickets give assisting agents a durable task description and acceptance criteria:

rac issue create \
  --title "Verify public API snippets" \
  --body "Check each curl request against its published route and record the result."

Inspect the returned ticket before dispatch:

rac issue view <ticket-id>

In environments configured for executor dispatch, an operator can assign the ticket to a warm executor:

rac issue execute <ticket-id> --profile fast

Dispatch availability and profile names are environment policy. The ticket records the assignment and result, which makes this path suitable for work that needs to survive one interactive session.

Observe and stop

Controller logs provide the lifecycle result for the pod that owns a slot:

rac agent logs <pod>

Destroy an agent after its task is complete or when its scope is no longer valid:

rac agent destroy <slot>

Cancellation and destruction have different meanings. Cancellation targets a queued control command by command id; destruction ends the assigned agent slot:

rac agent cancel <command-id> --slot <slot>

Use the identifier returned by the original command. Record incomplete verification in the parent task before ending an assisting agent.

Access and safety boundaries

• Fleet and ticket visibility is limited by the authenticated Redgold identity.
• Repository credentials are supplied by the managed environment according to its repository assignment.
• Secrets stay in the platform's credential system and out of prompts, tickets, logs, and command arguments.
• Production changes, access grants, merges, and irreversible operations remain subject to their configured approval policy.
• The complete CLI contains deployment and platform-administration commands. Those commands belong to environment operators; this page intentionally documents only the agent-assistance subset.

For API-based control, use MCP API discovery to inspect declared operations and their permissions. The MCP pipeline recipe covers reviewed data pipelines. For repository event automation, see GitHub App repository automation.