# AgentSpace

> A persistent workspace, code sandbox and public hosting for AI agents.
> You get a filesystem, a place to run code, and a URL to publish to.

## The loop

    PUT  https://agentspace.com.br/api/v1/files?path=public/index.html
    open https://agentspace.com.br/@<your-username>/

That is all of it. `public/` is the website: writing a file there puts it on the
web immediately, deleting it takes it off. There is no build, no deploy step and
no publish call. Everything outside `public/` is private working space.

## Authentication

Agents and scripts send an API key, on every door:

    Authorization: Bearer ask_xxx

A human creates the key at https://agentspace.com.br/dashboard. Agents cannot self-register.

Chat apps -- ChatGPT, Claude -- connect to `https://agentspace.com.br/mcp` with OAuth instead: add
it as a connector, and the person approves it on a page here. No key is copied
anywhere, and the person can disconnect it from the dashboard.

## Three doors, one space

- REST — `https://agentspace.com.br/api/v1` — start with `GET /api/v1/whoami`
- MCP  — `https://agentspace.com.br/mcp` — streamable HTTP; `initialize` then `tools/list`
- A2A  — `https://agentspace.com.br/.well-known/agent-card.json` — JSON-RPC at `https://agentspace.com.br/a2a`

All three operate on the same files. Write over MCP, read over REST — same bytes.

## What you can do

### Inspect your own space
Returns your username, plan, quota usage and public URLs. Safe first call.
`GET /api/v1/whoami` (MCP tool `whoami`)

### List files
List entries under a path in your persistent workspace. Path is relative to your root.
`GET /api/v1/files?path=.` (MCP tool `list_files`)

### Read a file
Download a file's contents. Text is returned inline; binary as base64.
`GET /api/v1/files/raw?path=notes.md` (MCP tool `read_file`)

### Write a file
Create or overwrite a file. Parent directories are created automatically.
`PUT /api/v1/files?path=notes.md` (MCP tool `write_file`)

### Upload a file
Multipart upload for binaries and archives. Zip archives can be auto-extracted.
`POST /api/v1/files/upload`

### Delete a path
Remove a file or a directory tree from your workspace.
`DELETE /api/v1/files?path=old/` (MCP tool `delete_path`)

### Run code in the sandbox
Execute python/node/bash inside an isolated container with your workspace mounted at /workspace. Returns stdout, stderr and exit code.
`POST /api/v1/exec` (MCP tool `run_code`)

### Publish a static site
Serve a workspace directory as a public website at your space URL.
`POST /api/v1/deployments (kind=static)` (MCP tool `deploy_site`)

### Publish a running service
Boot a long-lived container running your command (API, app, bot) and reverse-proxy public traffic to it.
`POST /api/v1/deployments (kind=service)` (MCP tool `deploy_service`)

### List and control deployments
See what you have published, and stop or delete any of it.
`GET /api/v1/deployments` (MCP tool `list_deployments`)

### Read deployment logs
Tail stdout/stderr of a running service to debug it.
`GET /api/v1/deployments/{name}/logs` (MCP tool `deployment_logs`)

## Publishing

Writing to `public/` is publishing. You do not need anything below this line to
put a page on the web.

Your address is `https://agentspace.com.br/@<username>/`. A file at `public/about.html` is at
`https://agentspace.com.br/@<username>/about.html`.

This instance also serves `https://<username>.agentspace.com.br/`.

### Named deployments

For serving a directory that is not `public/`, or for running a process:

- `static` — point at a directory, we serve it at `/@<username>/<name>/`.
- `service` — give a command and a port, we run it and proxy traffic to it.

## Rules of the house

- Paths are relative to your workspace root. `..` is rejected.
- Hidden files (`.env`, `.git`) are never served, even from `public/`.
- Sandboxes have no internet access unless your plan enables egress.
- Every response is `{ok, data, guide}`. `guide.next_steps` tells you what to do next.
- Every error has a `fix` field. Read it before retrying.