# Deploying Autonomous AI Agents

**Page:** guides/ai-agents

[Download Raw Markdown](./guides/ai-agents.md)

---

# Deploying Autonomous AI Agents

**Every AI agent framework has the same fatal flaw: the agent can think but it cannot act.**

It can generate code but cannot run it. It can plan a deployment but cannot execute it. It can describe a test but cannot open a browser. The agent is a brain in a jar, completely dependent on human hands to translate its intentions into reality.



Hoody gives agents a body.

When every service is an HTTPS endpoint — terminal, filesystem, database, browser, display, process manager — an AI agent does not need special adapters, custom plugins, or permission negotiations. It makes HTTP requests. That is what agents already know how to do. Every process the agent spawns is instantly a URL. Every tool it uses is a URL. And with the built-in `hoody-agent` service, you can orchestrate all of this through a single conversational interface — the agent manages itself.

**HTTP-native infrastructure is AI-native infrastructure.** This is not a coincidence. It is the design. And it all runs on servers you own, with container-level isolation, zero shared state, and a privacy-first architecture years in the making.


Drop [`https://hoody.com/skills/SKILL.lite.md`](https://hoody.com/skills/SKILL.lite.md) into the agent's system prompt and it knows what Hoody is, how to authenticate, and which namespace owns which task — for about 2 000 tokens. The agent fetches deeper detail on demand from [`INDEX.md`](https://hoody.com/skills/INDEX.md) or per-namespace files. See the [Agent Skill Bundle](/foundation/agent-skill-bundle/) for the full layout.


---

## Why Hoody Is the AI Execution Environment

Consider what an autonomous agent needs:

| Capability | Traditional Stack | Hoody |
|-----------|------------------|-------|
| Execute commands | SSH + credentials + firewall rules | `POST terminal-1.../api/v1/terminal/execute` |
| Read/write files | SFTP + mount points + permissions | `GET/POST files.../api/v1/files/...` |
| Query databases | Connection strings + drivers + ORM | `POST sqlite-1.../api/v1/sqlite/db` |
| Automate browsers | Puppeteer setup + Chromium install | `POST browser-1.../api/v1/browser/...` |
| Spawn more agents | Infrastructure provisioning | `POST /api/v1/containers` |
| Observe everything | Logging infrastructure | Every HTTP request is observable |

Every capability is one HTTP call. No SDK installation. No driver management. No authentication ceremony beyond a bearer token.


LLMs were trained on the web. They understand HTTP natively. When your infrastructure speaks HTTP, you are not teaching AI a new language -- you are speaking the one it already knows.


---

## Step 1: Create an Agent Container

Give your AI agent its own isolated computer:


  
    ```bash
    # Create a container for your agent
    hoody containers create --project $PROJECT_ID \
      --server-id $SERVER_ID \
      --name "ai-agent-alpha" \
      --container-image "debian-12" \
      --hoody-kit
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';

    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

    const agent = await client.api.containers.create(PROJECT_ID, {
      name: 'ai-agent-alpha',
      server_id: SERVER_ID,
      container_image: 'debian-12',
      hoody_kit: true,
    });

    console.log('Agent container:', agent.data.id);
    // Agent now has: terminal, files, sqlite, browser,
    // exec, display, code, daemon, cron, notifications...
    ```
  
  
    ```bash
    curl -X POST "https://api.hoody.icu/api/v1/projects/$PROJECT_ID/containers" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "ai-agent-alpha",
        "server_id": "'$SERVER_ID'",
        "container_image": "debian-12",
        "hoody_kit": true
      }'
    ```
  


That container is now a complete computer. The agent has all 18 HTTP services at its disposal. No setup required.

---

## Step 2: Use hoody-agent's 100+ Endpoints

The hoody-agent service is a full autonomous coding agent accessible entirely through HTTP:


  
    ```bash
    # The `hoody agent` CLI has subcommands (prompt, sessions, workspaces, tools, ...).
    # You can also drive it directly via HTTP to the agent service URL:
    curl -X POST "https://$PROJECT_ID-$AGENT_ID-workspaces-1.$SERVER.containers.hoody.icu/api/v1/agent/prompt/sync" \
      -H "Content-Type: application/json" \
      -d '{
        "parts": [{ "type": "text", "text": "Set up a Node.js REST API with user authentication, SQLite database, and automated tests. Deploy it as a daemon process." }],
        "autoApprove": true
      }'
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';

    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

    // Using raw fetch to show the HTTP surface directly.
    // The same endpoints are also available via client.agent.* in the SDK.
    const response = await fetch(
      `https://${PROJECT_ID}-${AGENT_ID}-workspaces-1.${SERVER}.containers.hoody.icu/api/v1/agent/prompt/sync`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          parts: [{ type: 'text', text: `Set up a Node.js REST API with user authentication,
                         SQLite database, and automated tests. Deploy it as a
                         daemon process.` }],
          autoApprove: true,
        }),
      }
    );

    const result = await response.json();
    console.log('Session ID:', result.sessionID);
    // Agent now autonomously:
    // 1. Installs Node.js via terminal
    // 2. Writes API code via file operations
    // 3. Creates database schema via SQLite
    // 4. Runs tests via terminal
    // 5. Starts daemon via daemon manager
    ```
  
  
    ```bash
    curl -X POST "https://$PROJECT_ID-$AGENT_ID-workspaces-1.$SERVER.containers.hoody.icu/api/v1/agent/prompt/sync" \
      -H "Content-Type: application/json" \
      -d '{
        "parts": [{ "type": "text", "text": "Set up a Node.js REST API with user authentication, SQLite database, and automated tests. Deploy it as a daemon process." }],
        "autoApprove": true
      }'
    ```
  


The agent now works autonomously. It reads files, writes code, executes commands, queries databases, and deploys services -- all through the same HTTP services available to any human user.

### Monitor in Real-Time

Stream agent output in real time with the non-sync prompt endpoint, which returns Server-Sent Events:

```typescript
// Stream real-time updates via SSE
const response = await fetch(
  `https://${PROJECT_ID}-${AGENT_ID}-workspaces-1.${SERVER}.containers.hoody.icu/api/v1/agent/prompt`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      parts: [{ type: 'text', text: 'Run the test suite and report results' }],
      autoApprove: true,
    }),
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
  // Streams tool calls, tool results, and assistant messages as they happen
}
```

Or view live sessions in your browser:

```
https://PROJECT_ID-AGENT_ID-workspaces-1.SERVER.containers.hoody.icu/api/v1/agent/sessions/live
```

You can also open the agent's built-in web UI directly:

```
https://PROJECT_ID-AGENT_ID-workspaces-1.SERVER.containers.hoody.icu
```

---

## Step 3: Give the Agent Full Access

An agent in a Hoody container has access to everything a human developer would:

### Terminal Access

```bash
# Agent can execute any shell command.
# ephemeral=true gives an isolated one-shot PTY; without it, terminal_id is required.
curl -X POST "https://$PROJECT_ID-$AGENT_ID-terminal-1.$SERVER.containers.hoody.icu/api/v1/terminal/execute?ephemeral=true" \
  -H "Content-Type: application/json" \
  -d '{"command": "git clone https://github.com/user/repo && cd repo && npm install && npm test"}'
```

### Filesystem Access

```bash
# Agent can read and write any file — upload is PUT /api/v1/files/{path} with the file content as the body
curl -X PUT "https://$PROJECT_ID-$AGENT_ID-files-1.$SERVER.containers.hoody.icu/api/v1/files/app/config.json" \
  -H "Content-Type: application/json" \
  -d '{"port": 3000, "env": "production"}'
```

### Database Access

```bash
# Agent can query and modify databases — the `db` query parameter is required
curl -X POST "https://$PROJECT_ID-$AGENT_ID-sqlite-1.$SERVER.containers.hoody.icu/api/v1/sqlite/db?db=/hoody/databases/app.db&create_db_if_missing=true" \
  -H "Content-Type: application/json" \
  -d '{"transaction": [{"query": "CREATE TABLE metrics (id INTEGER PRIMARY KEY, name TEXT, value REAL, timestamp DATETIME DEFAULT CURRENT_TIMESTAMP)"}]}'
```

### Browser Automation

```bash
# Agent can navigate websites, take screenshots, interact with UI.
# /screenshot navigates to the URL and captures it in one call (PNG by default).
curl "https://$PROJECT_ID-$AGENT_ID-browser-1.$SERVER.containers.hoody.icu/screenshot?url=http://localhost:3000&start=true" \
  --output page.png
```


The agent has full control inside its container -- and zero access outside it. It can `rm -rf /` and only destroy its own sandbox. This is why containers exist: radical autonomy within absolute boundaries.


---

## Multi-Agent Orchestration

Here is where Hoody's architecture becomes extraordinary. Because containers are peers connected by HTTP, agents can orchestrate other agents.

### Agent A Spawns and Controls Agent B

```typescript


const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

// Agent A: The Orchestrator
// Creates a specialized container for Agent B
const workerContainer = await client.api.containers.create(PROJECT_ID, {
  name: 'ai-worker-backend',
  server_id: SERVER_ID,
  container_image: 'debian-12',
  hoody_kit: true,
});

// Agent A assigns a task to Agent B via the agent service URL
// prompt/sync waits for completion before returning
const taskResponse = await fetch(
  `https://${PROJECT_ID}-${workerContainer.data.id}-workspaces-1.${SERVER}.containers.hoody.icu/api/v1/agent/prompt/sync`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      parts: [{ type: 'text', text: 'Implement the payment processing module with Stripe integration. Write tests. Do not deploy until all tests pass.' }],
      autoApprove: true,
    }),
  }
);
const result = await taskResponse.json();
// result.status is already 'completed' or 'failed' — no polling needed

// Agent A inspects Agent B's work by reading its files directly via kit services
const containerClient = await client.withContainer({
  id: workerContainer.data.id,
  project_id: PROJECT_ID,
  server: SERVER,
});

const code = await containerClient.files.get('/app/src/payments.ts');

// Agent A runs Agent B's tests from Agent B's terminal (ephemeral one-shot PTY)
const testResult = await containerClient.terminal.execution.execute({
  command: 'cd /app && bun test payments',
}, { ephemeral: true });
```

This is not theoretical. This is HTTP calls between containers. Agent A literally controls Agent B's terminal, reads its files, queries its database. No message queue. No coordinator service. Just URLs talking to URLs.

### The Floating Architecture in Practice

```
┌─────────────────────┐
│  ORCHESTRATOR (A)   │
│  Plans architecture │
│  Assigns tasks      │
│  Reviews work       │
└──────────┬──────────┘
           │ HTTP
     ┌─────┴─────┐
     v           v
┌──────────┐ ┌──────────┐
│ WORKER B │ │ WORKER C │
│ Backend  │ │ Frontend │
│ code     │ │ code     │
└──────────┘ └──────────┘
     │           │
     │ HTTP      │ HTTP
     v           v
┌──────────┐ ┌──────────┐
│ WORKER D │ │ WORKER E │
│ Tests    │ │ Design   │
│ & QA     │ │ review   │
└──────────┘ └──────────┘
```

Each worker is an isolated container with its own agent, terminal, files, and database. The orchestrator coordinates via HTTP. Workers can spawn sub-workers. It is agents all the way down.

---

## MCP Client Integration

Hoody Agent includes a production-ready MCP (Model Context Protocol) client that connects to external MCP servers, dynamically discovering their tools at runtime via `client.listTools()`:


  
    ```bash
    # Connect an external MCP server (e.g., GitHub) to your agent.
    # Local servers use type:"local" with command as a single array (command + args).
    curl -X POST "https://$PROJECT_ID-$AGENT_ID-workspaces-1.$SERVER.containers.hoody.icu/api/v1/workspaces/${WORKSPACE_ID}/mcp" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "github",
        "config": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-github"] }
      }'
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';

    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

    // Using raw fetch to show the HTTP surface directly.
    // The same endpoints are also available via client.agent.* in the SDK.
    await fetch(
      `https://${PROJECT_ID}-${AGENT_ID}-workspaces-1.${SERVER}.containers.hoody.icu/api/v1/workspaces/${WORKSPACE_ID}/mcp`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          name: 'github',
          // Local servers: type:"local" + command as a single array (command + args).
          config: { type: 'local', command: ['npx', '-y', '@modelcontextprotocol/server-github'] },
          // Tools are dynamically discovered from connected MCP servers.
          // Remote servers use { type: 'remote', url: '...' } instead.
        }),
      }
    );
    ```
  
  
    ```bash
    curl -X POST "https://$PROJECT_ID-$AGENT_ID-workspaces-1.$SERVER.containers.hoody.icu/api/v1/workspaces/${WORKSPACE_ID}/mcp" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "github",
        "config": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-github"] }
      }'
    ```
  


With MCP servers connected, the agent dynamically discovers and merges their tools with its built-in capabilities. Connect GitHub, Slack, Jira, custom APIs, or any MCP-compatible server -- all orchestrated through the same HTTP interface.

---

## Autonomous Deployment Workflow

Here is a real-world pattern: an AI agent that deploys your application end-to-end.

```typescript


const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

// Step 1: Snapshot before deployment (safety net)
// Capture the alias so the rollback can reference the exact same snapshot.
const snapshotAlias = `pre-deploy-${Date.now()}`;
await client.api.containers.createSnapshot(PRODUCTION_ID, {
  alias: snapshotAlias,
});

// Step 2: Agent pulls latest code and deploys via agent service URL
// prompt/sync waits for the agent to finish before returning
const deployResponse = await fetch(
  `https://${PROJECT_ID}-${PRODUCTION_ID}-workspaces-1.${SERVER}.containers.hoody.icu/api/v1/agent/prompt/sync`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      parts: [{ type: 'text', text: `
        1. Pull latest code from main branch
        2. Install dependencies
        3. Run full test suite -- stop if any test fails
        4. Build production assets
        5. Restart the daemon process
        6. Run smoke tests against the live URL
        7. Report status via notification
      ` }],
      autoApprove: true,
    }),
  }
);
const result = await deployResponse.json();

// prompt/sync is synchronous -- result.status is already final
if (result.status === 'failed') {
  // Rollback: restore the snapshot created in Step 1
  await client.api.containers.restoreSnapshot(PRODUCTION_ID, snapshotAlias);

  // Notify the team via kit notifications service
  const containerClient = await client.withContainer({
    id: PRODUCTION_ID,
    project_id: PROJECT_ID,
    server: SERVER,
  });
  await containerClient.notifications.notify.trigger({
    summary: 'Deployment Failed',
    body: `Rolled back to pre-deploy snapshot. Finish reason: ${result.info?.finish ?? 'unknown'}`,
    display: '0',
  });
}
```

The agent handles the entire deployment pipeline. If anything goes wrong, the snapshot restores everything in seconds. No CI/CD platform needed. No YAML files. Just an agent, HTTP calls, and a safety net.

---

## Safeguards: The Snapshot-First Pattern

AI agents are powerful but unpredictable. The snapshot-first pattern is your insurance:


  
    ```bash
    # ALWAYS snapshot before letting an agent run
    hoody snapshots create -c $AGENT_ID \
      --alias "before-agent-experiment"

    # Let the agent work via direct HTTP to agent service
    curl -X POST "https://$PROJECT_ID-$AGENT_ID-workspaces-1.$SERVER.containers.hoody.icu/api/v1/agent/prompt/sync" \
      -H "Content-Type: application/json" \
      -d '{"parts": [{"type": "text", "text": "Refactor the entire codebase to use TypeScript 5 features"}], "autoApprove": true}'

    # If the agent breaks something:
    hoody snapshots restore -c $AGENT_ID --name "before-agent-experiment"
    ```
  
  
    ```typescript
    import { HoodyClient } from '@hoody-ai/hoody-sdk';

    const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });

    // Snapshot first -- always
    await client.api.containers.createSnapshot(AGENT_ID, {
      alias: 'before-agent-experiment',
    });

    // Let the agent work via direct HTTP to agent service
    await fetch(
      `https://${PROJECT_ID}-${AGENT_ID}-workspaces-1.${SERVER}.containers.hoody.icu/api/v1/agent/prompt/sync`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          parts: [{ type: 'text', text: 'Refactor the entire codebase to use TypeScript 5 features' }],
          autoApprove: true,
        }),
      }
    );

    // If the agent breaks something:
    await client.api.containers.restoreSnapshot(AGENT_ID, 'before-agent-experiment');
    ```
  
  
    ```bash
    # Snapshot first
    curl -X POST "https://api.hoody.icu/api/v1/containers/$AGENT_ID/snapshots" \
      -H "Authorization: Bearer $HOODY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"alias": "before-agent-experiment"}'

    # Let the agent work
    curl -X POST "https://$PROJECT_ID-$AGENT_ID-workspaces-1.$SERVER.containers.hoody.icu/api/v1/agent/prompt/sync" \
      -H "Content-Type: application/json" \
      -d '{"parts": [{"type": "text", "text": "Refactor the entire codebase to use TypeScript 5 features"}], "autoApprove": true}'

    # If the agent breaks something (restore = PATCH the snapshot)
    curl -X PATCH "https://api.hoody.icu/api/v1/containers/$AGENT_ID/snapshots/before-agent-experiment" \
      -H "Authorization: Bearer $HOODY_TOKEN"
    ```
  



Never let an AI agent modify a container without snapshotting first. Agents are confident, creative, and occasionally catastrophically wrong. Snapshots make that acceptable.


---

## Container Isolation for Experiments

The most dangerous thing about AI agents is not that they make mistakes -- it is that mistakes can propagate. Container isolation prevents this absolutely:

- **Each agent runs in its own container** -- One agent cannot access another's filesystem, processes, or network unless explicitly connected via HTTP
- **Experiments are sandboxed** -- An agent testing a destructive migration cannot touch your production data
- **Failures are contained** -- If an agent installs malicious packages or runs a fork bomb, only its container is affected
- **Evidence is preserved** -- Snapshot the container after an agent run to audit exactly what it did

This is why bare metal + containers is the correct architecture for AI. Not because it is more convenient -- because it is physically safe.

---

## @hoody.com: External AI Access

`@hoody.com` is SSH for the AI era. Any AI agent with web access — ChatGPT, Claude, Claude Code, Cline, Roo Code, Codex — can give `@hoody.com` and immediately receive a Skill: structured instructions for controlling your entire infrastructure via HTTP. No adapter, no plugin, no custom integration. The agent fetches a URL and learns your API. From that point on it can spawn containers, execute code, read files, query databases — everything covered in this guide — from any platform that can make an HTTP request.

You're also never locked into a provider. Hoody supports 75+ AI providers — Anthropic, OpenAI, Google, Mistral, Groq, local Ollama models, any OpenAI-compatible endpoint. Swap models in a config change. A/B test Claude against GPT-4o across two containers. Today Claude, next week your own fine-tuned Llama. The agents you build here work with all of them. See [Hoody AI](/foundation/hoody-ai/) for the full provider list.

---

## MITM Rules: Control Agent Behavior Without Code

Autonomous agents are powerful. That power needs guardrails. hoody-agent ships with a built-in rule engine that lets you observe, control, and modify every interaction your agents make — without writing a single line of proxy code.

Define rules in JSON. A `chat.system.transform` rule appends "Never delete files in /data without confirmation" to every system prompt for `prod`-tagged sessions. A `tool.execute.before` rule sends a notification to your phone when any agent is about to run `bash`. A `session.error` rule fires a webhook to PagerDuty when an agent fails. Seven event types, five action types, per-session tag filtering, regex content matching, cooldowns — all declarative, all in your config file or the Settings UI.

This is agent control at the protocol level. Because AI is HTTP, and because hoody-agent hooks into the session lifecycle directly, you get real-time introspection into every tool call, every message, every prompt — per agent, per session, per tool. See the full documentation at [MITM: Built-In Rule Engine](/foundation/hoody-ai/mitm/#built-in-rule-engine-zero-code-mitm).

---

## What's Next

- **[The Vibe Coding Revolution](/guides/vibe-coding/)** -- Watch AI build your app in real-time
- **[Multiplayer by Default](/guides/multiplayer/)** -- Humans and agents collaborating simultaneously
- **[Zero-Knowledge Workflows](/guides/zero-knowledge/)** -- Keep agent experiments private and encrypted