$ npx agentvoy create my-project

  ? What do you want to build?
  > Agent — Local agent for development & experimentation
    App   — Deployable agentic app (API + UI + Docker + cloud)

npx agentvoy create my-project --yes
# Creates: my-project-agent/

my-project-agent/
├── agent.py           # Agent logic
├── tools.py           # Custom tools
├── run.py             # Interactive REPL
├── agent.guard.yml    # Guardrails & permissions
├── requirements.txt
└── .env.example

npx agentvoy create my-project --build-mode app --deploy-target docker --yes
# Creates: my-project-app/

my-project-app/
├── src/
│   ├── agents/
│   │   └── agent.py          # Agent logic
│   ├── tools/
│   │   └── tools.py          # Custom tools
│   ├── trace/
│   │   └── tracer.py         # Execution tracing (auto-generated)
│   └── config/
│       └── settings.py
├── server.py                  # FastAPI — /run, /health, /dev, /ws/trace
├── streamlit_app.py           # Chat UI with model picker & glass theme
├── devtools.html              # Real-time agent DevTools dashboard
├── Dockerfile
├── docker-compose.yml
├── agent.guard.yml
├── requirements.txt
└── .env.example

npx agentvoy create my-project --build-mode app --agent-mode multi --yes
# Creates: researcher → writer → reviewer pipeline

src/
├── agents/
│   ├── researcher.py
│   ├── writer.py
│   └── reviewer.py
└── pipeline.py          # Sequential orchestration

# Interactive — guided prompts for framework, model, and build mode
npx agentvoy create my-project

# Agent mode with defaults (OpenAI + GPT-4o)
npx agentvoy create my-project --yes

# App with Docker, fully non-interactive
npx agentvoy create my-project \
  --framework openai \
  --provider anthropic \
  --model claude-sonnet-4-20250514 \
  --build-mode app \
  --deploy-target docker \
  --yes

# Add guardrails to an existing project
npx agentvoy init

# Validate your config
npx agentvoy validate

cd my-project-app
agentvoy dev

cd my-project-app
agentvoy deploy --target docker

agentvoy deploy --target docker
# Builds: docker build -t my-project .
# Runs:   docker run -p 8080:8080 --env-file .env my-project
# Agent:  http://localhost:8080
# DevTools: http://localhost:8080/dev

agentvoy deploy --target fly-io
# Checks flyctl auth, sets secrets from .env, deploys
# Live URL: https://my-project.fly.dev
# DevTools: https://my-project.fly.dev/dev

agentvoy deploy --target docker --dry-run

? Deployment target:
> Docker
  Fly.io
  Railway
  GCP Cloud Run
  AWS Lambda

cd my-project-agent
npx agentvoy deploy --target docker

guardrails:
  behavior:
    timeout: 5m       → Docker HEALTHCHECK interval, Cloud Run timeout
    cost_limit: $1.00 → Container memory limit (512Mi)
permissions:
  execution:
    allow_shell: false → non-root Docker user

version: "1.0"

identity:
  name: my-agent
  description: Research assistant agent
  version: 0.1.0

model:
  provider: anthropic
  model: claude-sonnet-4-20250514
  api_key_env: ANTHROPIC_API_KEY

permissions:
  network:
    mode: restricted
    allow: ["*.github.com", "*.stackoverflow.com"]
  filesystem:
    read: ["./**"]
    write: ["./output/**"]
  tools:
    require_approval: ["delete_*", "send_*", "deploy_*"]
  execution:
    allow_shell: false
    allow_subprocess: false

guardrails:
  input:
    block_prompt_injection: true
    max_tokens: 4096
    pii_detection: warn
    content_filter: moderate
  output:
    block_harmful_content: true
    max_output_tokens: 8192
  behavior:
    max_iterations: 20
    timeout: 5m
    cost_limit: "$1.00"

observability:
  tracing: true
  log_level: info
  cost_tracking: true

pip install agentvoy-guard

from agentvoy_guard import Guard

guard = Guard.from_config()  # reads agent.guard.yml

with guard.session() as session:
    session.check_input(user_prompt)
    result = my_agent.run(user_prompt)
    session.check_output(result)

agentvoy create [name]     # Create a new agent or app project
agentvoy dev               # Start agent server with DevTools dashboard (app mode)
agentvoy deploy            # Deploy to Docker, Fly.io, or other targets
agentvoy init              # Add agent.guard.yml to an existing project
agentvoy validate          # Validate your agent.guard.yml config
agentvoy list              # List supported frameworks, models, and targets

agentvoy/                        # TypeScript monorepo
  packages/
    core/                        # Types, config, adapters, deployers
      src/
        adapters/                # Framework adapters (openai, crewai, …)
        deployers/               # Deployment adapters (docker, fly-io, …)
          tracer.ts              # Agent execution tracer generator
          devtools-dashboard.ts  # DevTools HTML dashboard generator
          api-wrapper.ts         # server.py generator (with /dev endpoints)
          streamlit-app.ts       # Streamlit chat UI generator
          pipeline.ts            # Multi-agent pipeline generator
        types.ts                 # Universal type system
        config.ts                # agent.guard.yml parser
    cli/                         # agentvoy CLI (create, dev, deploy, init, validate, list)
    create-agentvoy/             # npx create-agentvoy shorthand

agentvoy-guard/                  # Python runtime enforcement package

git clone https://github.com/agentvoy/agentvoy.git
cd agentvoy
npm install
npm run build

# Smoke test agent mode
node packages/cli/dist/index.js create test-project --yes

# Smoke test app mode
node packages/cli/dist/index.js create test-project --build-mode app --deploy-target docker --yes

# Test DevTools
cd test-project-app
pip install -r requirements.txt
agentvoy dev  # opens http://localhost:8080/dev