Deploy from Claude Code, Codex & Cursor¶

You wrote an agent. It works locally. Now you want it in production with identity propagation, policy enforcement, and approval workflows — without opening a browser.

This guide covers three paths, all terminal-native:

Prerequisites¶

1. Get a RunAgents workspace

Sign up at try.runagents.io. You receive a workspace URL and API key.

2. Install the CLI

curl -fsSL https://runagents-releases.s3.amazonaws.com/cli/install.sh | sh

# Verify
runagents version
# runagents 1.1.1

3. Configure

runagents config set endpoint https://YOUR_WORKSPACE.try.runagents.io
runagents config set api-key ra_YOUR_API_KEY
runagents config set namespace default

Your API key is in the console under Settings → API Keys, or ask the copilot:

runagents copilot chat "where do I find my API key?"

Path A: Copilot Shell¶

The fastest path. Type what you want — the copilot detects your code, proposes resources, and deploys after your confirmation.

runagents copilot

RunAgents Copilot — type a command or describe what you want

> deploy this folder as support-agent

Analyzing 3 source files in ./...
  ✓ Detected: stripe (https://api.stripe.com), slack (https://slack.com/api)
  ✓ Detected: openai gpt-4o-mini

I'll create the following:
  1. Register tool:  stripe   (https://api.stripe.com, OAuth2)
  2. Register tool:  slack    (https://slack.com/api, API Key)
  3. Deploy agent:   support-agent (gpt-4o-mini)

Confirm? [y/n] y

  ✓ Tool registered: stripe
  ✓ Tool registered: slack
  ✓ Agent deployed:  support-agent (Running)

> test it: look up stripe customer alice@example.com

Invoking support-agent...
  → Tool call: stripe/v1/customers/search (200 OK)
  ✓ Response: Customer found — Alice Smith, plan: Pro

Using the copilot from inside Claude Code¶

Add a .claude/commands/deploy.md to your project:

Deploy the current agent to RunAgents:
1. Run `runagents copilot` in the terminal
2. Type: deploy this folder as [AGENT_NAME]
3. Confirm the proposed resources

Or just run it directly in the Claude Code terminal panel:

# Inside your Claude Code project
runagents copilot
> deploy this folder as my-agent

Path B: Action Plans with Claude Code or Codex¶

The most powerful path for teams. Your AI tool generates a structured deployment plan, you review it, validate it, and apply it. Plans are JSON files you can commit to version control.

Step 1: Export workspace state¶

runagents context export -o json > runagents-context.json

This snapshot includes all registered tools, model providers, agents, policies, and deploy drafts in your workspace.

Step 2: Ask your AI tool to write the plan¶

I have an agent in agent.py that calls Stripe and Slack.
Read runagents-context.json to see my current RunAgents workspace.

Generate a file called plan.json that:
1. Registers stripe as a tool (https://api.stripe.com, OAuth2)
2. Registers slack as a tool (https://slack.com/api, API Key)
3. Deploys agent.py as "support-agent" using gpt-4o-mini

Follow the RunAgents action plan schema:
https://github.com/runagents-io/runagents/blob/main/docs-site/docs/cli/plan-schema.json

{
  "plan_id": "deploy-support-agent",
  "continue_on_error": false,
  "actions": [
    {
      "id": "register-stripe",
      "type": "tool.upsert",
      "idempotency_key": "tool-stripe-v1",
      "params": {
        "name": "stripe",
        "spec": {
          "connection": { "baseUrl": "https://api.stripe.com" },
          "authType": "OAuth2"
        }
      }
    },
    {
      "id": "register-slack",
      "type": "tool.upsert",
      "idempotency_key": "tool-slack-v1",
      "params": {
        "name": "slack",
        "spec": {
          "connection": { "baseUrl": "https://slack.com/api" },
          "authType": "ApiKey"
        }
      }
    },
    {
      "id": "deploy-agent",
      "type": "deploy.execute",
      "idempotency_key": "deploy-support-agent-v1",
      "params": {
        "agent_name": "support-agent",
        "source_files": { "agent.py": "<contents>" },
        "llm_configs": [{ "provider": "openai", "model": "gpt-4o-mini" }],
        "required_tools": ["stripe", "slack"]
      }
    }
  ]
}

Files: runagents-context.json, agent.py

Generate a RunAgents action plan (plan.json) to:
- Register stripe (https://api.stripe.com, OAuth2)
- Register slack (https://slack.com/api, API Key)
- Deploy agent.py as "support-agent" using gpt-4o-mini

Schema reference: https://github.com/runagents-io/runagents/blob/main/docs-site/docs/cli/plan-schema.json
Each action needs: id, type, idempotency_key, params

Using runagents-context.json as the current workspace state,
create plan.json to deploy agent.py as "support-agent".
Register stripe and slack tools first.
Follow the RunAgents action plan schema.

Step 3: Validate before applying¶

runagents action validate --file plan.json

Plan: deploy-support-agent  (3 actions)

  ✓ tool.upsert         register-stripe       valid
  ✓ tool.upsert         register-slack        valid
  ✓ deploy.execute      deploy-agent          valid

All 3 actions valid. Ready to apply.

Validation checks required fields, schema correctness, and duplicate idempotency keys. Nothing is created yet.

Step 4: Apply¶

runagents action apply --file plan.json

Applying plan: deploy-support-agent

  ✓ register-stripe      applied   (tool: stripe)
  ✓ register-slack       applied   (tool: slack)
  ✓ deploy-agent         applied   (agent: support-agent, status: Running)

3/3 actions applied successfully.

# In your CI pipeline (GitHub Actions, etc.)
- name: Deploy to RunAgents
  env:
    RUNAGENTS_ENDPOINT: ${{ secrets.RUNAGENTS_ENDPOINT }}
    RUNAGENTS_API_KEY: ${{ secrets.RUNAGENTS_API_KEY }}
  run: |
    runagents action validate --file plan.json
    runagents action apply --file plan.json

Path C: Direct CLI Deploy¶

For simple agents where you know the tools and model upfront.

runagents deploy \
  --name support-agent \
  --file agent.py \
  --tool stripe \
  --tool slack \
  --model openai/gpt-4o-mini

Analyzing agent.py...
  Detected tools:      stripe, slack
  Detected LLM usage:  gpt-4o-mini
  Entry point:         agent.py

Deploying agent "support-agent"...
  ✓ Tool mapped:     stripe
  ✓ Tool mapped:     slack
  ✓ Agent deployed:  support-agent (Running)

The --tool flag references tools already registered in your workspace. If a tool doesn't exist yet, create it first using runagents tools create --file <tool.json> or action plans.

What Gets Created¶

Regardless of which path you use, the platform creates the same resources:

Your agent code runs unchanged. No secrets, no API keys — all credentials are injected at the network layer.

Check it's running¶

# Status
runagents agents get default support-agent

# Tail recent runs
runagents runs list --agent support-agent

# View run events
runagents runs get run-XXXXX

Or open the console — navigate to Agents → support-agent → Playground — and send a test message.

What changed vs running locally¶

Next Steps¶