agv 0.3.10

AgentEnv Cloud CLI and Python SDK for sandboxes, notebooks, clusters, and AI workloads

AgentEnv CLI

A command-line interface for AgentEnv Cloud - manage containers, sandboxes, and more.

Installation

pip install agv

This package publishes the Python module as agentenv and installs two CLI entrypoints:

• agv: package-aligned short command
• agentenv: explicit command name for documentation and shell usage

The examples below keep using agv, but agentenv is equivalent:

agv version
agentenv version
python -m agentenv version

Quick Start

# Authenticate with an API key
agv login --api-key sk_live_xxxxx

# Set default sandbox type
agv set type xl

# Run a Python sandbox
agv run -- python3 -m http.server

# List sandboxes
agv ls

# View logs
agv logs -f <sandbox-id>

Ray / Spark Clusters

The CLI now includes cluster lifecycle commands, and the Python SDK also exposes higher-level helpers that can provision Ray/Spark clusters and connect to the cluster head over a direct public endpoint.

Cluster CLI

agv cluster ray 4x2xH100 --workspace <workspace-id>
agv cluster spark 2xH100 --workspace <workspace-id> --wait
agv cluster ls
agv cluster inspect <cluster-id>
agv cluster stop <cluster-id>

Direct-connect requires the scheduler to be able to resolve the head hypervisor public IP and (best-effort) open inbound security group rules for allow_cidr. If that integration is not configured, the cluster may start but metadata.rayAddress / metadata.sparkRemote will be missing and auto-connect will fail.

Install optional client deps if you want auto-connect:

pip install "agv[ray]"
pip install "agv[spark]"

The spark extra installs PySpark plus Spark Connect runtime deps (pandas/pyarrow/grpcio/grpcio-status/zstandard). Keep the PySpark major/minor in sync with the Spark server version (defaults to Spark 3.5.x).

Ray (Ray Client)

import agentenv as agv

# Shape formats:
# - "4x2xH100" => head + 4 workers, 2x H100 per worker
# - "2xH100"   => single node (head only), 2x H100 on the head
cluster = agv.ray_init("4x2xH100", allow_cidr="1.2.3.4/32")

import ray

@ray.remote
def f(x):
    return x + 1

print(ray.get(f.remote(1)))

cluster.close(stop_cluster=True)

Spark (Spark Connect)

import agentenv as agv

spark = agv.spark_init("4x2xH100", allow_cidr="1.2.3.4/32")
print(spark.range(10).count())

spark.close(stop_cluster=True)

Notes:

• spark.remote is a standard Spark Connect URL that includes an auth param: sc://<host>:<port>/;x-api-key=<token>.
• The Spark head image must include the gRPC auth proxy dependency (haproxy). Use Dockerfile.spark and scripts/ci/build-public-spark-image.sh, then set SPARK_IMAGE_DEFAULT on the api-server (or pass image= explicitly).

Commands

Authentication

agv login --api-key <key>           # Login with API key
agv login                           # Browser-based login
agv login --username <user> --password <pass>  # Local dev login
agv logout                          # Logout
agv auth status                     # Show auth status
agv auth create-key "My CLI Key"    # Create API key
agv auth list-keys                  # List API keys

Sandbox Management

agv run --type xl -- python3 -m http.server    # Create and run
agv run --expose 8080:http -- node server.js   # With port exposed
agv ls                                         # List sandboxes
agv inspect <id>                              # Show details
agv logs -f <id>                              # Follow logs
agv stop <id>                                 # Stop sandbox
agv rm <id>                                   # Delete sandbox

Preset Types

Type	CPU	Memory
micro	500	512 MB
small	2000	4 GB
medium	4000	8 GB
large	8000	16 GB
xl	16000	32 GB

Snapshots

agv snapshot create <sandbox-id> --name "My Environment"
agv snapshot ls
agv snapshot restore <snapshot-id>

Apps

agv app create --name web --port 8080 --min 0 --max 3
agv app create --name api --port 8080 --ready http_health --health-path /health
agv app deploy web --snapshot <snapshot-id>
agv app ls
agv app inspect <app-id-or-slug>
agv app logs <app-id-or-slug>
agv app rm <app-id-or-slug>

Notes:

• Ready types: port_accessible, http_health.
• If you specify http_health without --health-path, the CLI defaults to /health.

agv.function (Single-node remote function)

import agentenv as agv

@agv.function("small", image="python:3.11-slim")
def add(x, y):
    return x + y

print(add(2, 3))

Using an ImageBuilder:

import agentenv as agv

builder = agv.py().python_packages(["numpy"])

@agv.function("small", image=builder)
def norm(x):
    import numpy as np
    return float(np.linalg.norm(x))

print(norm([3, 4]))

Notes:

• Only single-node specs are supported (preset types like small, or cpu:mem).
• The function must be importable in the sandbox image (no nested or __main__ functions).

Browser Sessions

agv browser create                    # Create browser session
agv browser create --screen-width 1920 --screen-height 1080 --stealth
agv browser create --profile-mode ephemeral --rrweb
agv browser ls
agv browser inspect <id>

Managed Agents

agv managed-agent ls --workspace <workspace-id>
agv managed-agent create --name "Research Agent" --workspace <workspace-id> --upstream-id <upstream-id>
agv managed-agent create --name "Research Agent" --workspace <workspace-id> --upstream-id <upstream-id> --image docker://registry.example/tintin-managed-agent:latest
agv managed-agent create --name "Focused Agent" --workspace <workspace-id> --upstream-id <upstream-id> --skill-id <skill-id> --mcp-id <mcp-id>
agv managed-agent inspect <agent-id>
agv managed-agent messages <agent-id>
agv managed-agent send <agent-id> -- "summarize the repo status"
agv managed-agent wake <agent-id>
agv managed-agent fork <agent-id>
agv managed-agent rm <agent-id> --force

# Skills
agv managed-agent skill upload ./my-skill.zip --workspace <workspace-id> --name "PR reviewer"
agv managed-agent skill ls --workspace <workspace-id>
agv managed-agent skill assign <agent-id> <skill-id>
agv managed-agent skill unassign <agent-id> <skill-id>
agv managed-agent skill rm <skill-id> --force

# MCP servers
agv managed-agent mcp create --name GitHub \
  --config '{"command":"npx","args":["-y","@modelcontextprotocol/server-github"]}' \
  --workspace <workspace-id> \
  --secret-refs '{"env":{"GITHUB_TOKEN":"secret_abc123"}}'
agv managed-agent mcp ls --workspace <workspace-id>
agv managed-agent mcp assign <agent-id> <mcp-id>
agv managed-agent mcp unassign <agent-id> <mcp-id>
agv managed-agent mcp rm <mcp-id> --force

# Telegram binding
agv workspace secret-set <workspace-id> TELEGRAM_BOT_TOKEN '<telegram-bot-token>'
agv managed-agent telegram bind <agent-id> \
  --workspace <workspace-id> \
  --name "Telegram Agent" \
  --bot-token-key TELEGRAM_BOT_TOKEN \
  --bot-username agentbot
agv managed-agent telegram ls --workspace <workspace-id>
agv managed-agent telegram sync-webhook <integration-id> --workspace <workspace-id>
agv managed-agent telegram enable <integration-id> --workspace <workspace-id>
agv managed-agent telegram unbind <integration-id> --workspace <workspace-id>

• agv managed-agent create --image ... overrides the server default image for this agent.
• agv managed-agent create without --image uses the server-configured default image (MANAGED_AGENT_IMAGE).
• New managed agents enable all installed workspace skills and MCP definitions by default. Repeat --skill-id or --mcp-id during create to select a subset.
• agv managed-agent create prints Public Token: <token> in non-JSON output when the create response includes one.
• The create-time token can be reused as ?token=... on /v1/public/managed-agent/* helper routes such as GET /v1/public/managed-agent/messages or POST /v1/public/managed-agent/messages.
• agv managed-agent inspect does not regenerate that token later.
• Skill archives must be safe .zip bundles smaller than 50 MB with SKILL.md in the archive.
• Skills and MCP definitions are workspace-scoped. Commands that create or list them accept --workspace; if omitted, the selected CLI workspace is used.
• Assignment commands only apply skills and MCP definitions to agents in the same workspace.
• MCP --config matches Codex mcp_servers config: use command/args for STDIO or url for HTTP/SSE servers. --secret-refs points to workspace secret IDs, never plaintext.
• Telegram binding stores token references by workspace secret key. The raw bot token should live in agv workspace secret-set, not in command history or source code.

Notebook Sessions

agv notebook session create --workspace <workspace-id>
agv notebook session create --workspace <workspace-id> --type xl
agv notebook session create --workspace <workspace-id> --image docker://quay.io/jupyter/datascience-notebook:notebook-7.5.5
agv notebook session create --workspace <workspace-id> --storage-mode persistent --idle-ttl 600
agv notebook session list
agv notebook session get <id>

API Coverage

The CLI focuses on common day-to-day workflows. The Mintlify site and checked-in OpenAPI schema document the full api-server surface, including operational resources such as proxy usage, captcha usage, and webhook ingress.

Workspaces

agv workspace create "My Workspace"
agv workspace ls
agv workspace use <workspace-id>
agv workspace secret-set <ws-id> KEY value

Files

agv file upload ./myfile.txt
agv file download /remote.txt ./local.txt
agv file ls

Workflows

agv workflow ls
agv workflow create "Daily Sync" --file workflow.json
agv workflow inspect <workflow-id>
agv workflow update <workflow-id> --file workflow.json
agv workflow deploy <workflow-id>
agv workflow undeploy <workflow-id>
agv workflow execute <workflow-id> --input '{"customerId":"cus_123"}'
agv workflow execute-in-memory --workspace-id <workspace-id> --file workflow.json
agv workflow executions <workflow-id>
agv workflow execution <workflow-id> <execution-id>
agv workflow cancel <workflow-id> <execution-id>
agv workflow metrics <workflow-id>
agv workflow metrics-timeseries <workflow-id> --interval day
agv workflow node-definitions
agv workflow node-definition webhook
agv workflow plugins

Billing

agv balance                           # Show balance
agv billing history                   # Transaction history

Configuration

agv set type xl                       # Set default type
agv set image python:3.11             # Set default image
agv set workspace <workspace-id>      # Set default workspace
agv config show                       # Show configuration

AI Gateway

The CLI includes full support for the AgentEnv AI Gateway:

# Chat with AI models
agv ai chat "Hello!" --model gpt-4

# Manage providers
agv ai upstreams list
agv ai pools create --name production

# See the dedicated AI Gateway guide for complete documentation

See the AI Gateway guide: https://github.com/agentenv/monorepo/blob/main/cli/README-AI-GATEWAY.md

Configuration

The CLI reads configuration from multiple sources (in priority order):

1. Command-line flags (--api-url, --workspace, etc.)
2. Environment variables (AGENTENV_API_URL, AGENTENV_API_KEY, etc.)
3. Config file (~/.agentenv/config.yaml)
4. Project .env file
5. Built-in defaults

Config File (~/.agentenv/config.yaml)

api_url: http://localhost:3000
workspace: wk_abc123

defaults:
  type: small
  image: docker.io/library/python:3.11-slim
  cpu: 2000
  memory: 4096
  region: us-east-1

Use the API root as api_url without /v1. If you do pass a /v1 suffix, the CLI normalizes it automatically.

Release

Build release artifacts locally:

cd cli
uv build
python3 -m twine check dist/*

Release flow:

# 1. Bump the package version in cli/src/agentenv/_version.py

# 2. Sanity-check the version metadata
cd cli
python3 scripts/check_release_version.py --print-version

# 3. Build and validate the distributions
uv build
python3 -m twine check dist/*

# 4. Tag the release with the enforced format
git tag "agv-v$(python3 scripts/check_release_version.py --print-version)"
git push origin --tags

Upload them manually when you have PyPI credentials. The API token is read from environment/config (TWINE_PASSWORD, with TWINE_USERNAME=__token__):

TWINE_USERNAME=__token__ TWINE_PASSWORD="$PYPI_API_TOKEN" python3 -m twine upload dist/*

The repository also includes a GitHub Actions workflow for trusted publishing to PyPI, and it rejects tags whose version does not match the package version.