Skip to content

Commit ff98de2

Browse files
robertohlunarobertohluna
committed
docs: add AGENTS.md (universal agent guide) and CLAUDE.md (Claude Code project guide)
1 parent 2d9e86c commit ff98de2

2 files changed

Lines changed: 332 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# MIOSA for AI Agents
2+
3+
A universal guide for any AI agent (Claude, GPT, Gemini, open models) to drive MIOSA cloud infrastructure.
4+
5+
## What is MIOSA
6+
7+
MIOSA gives AI agents:
8+
9+
- **Sandboxes** — headless Firecracker microVMs for code execution
10+
- **Computers** — full desktop VMs (Linux XFCE) for browser/GUI automation
11+
- **Deployments** — git-backed web hosting with builds, releases, custom domains
12+
- **Storage** — S3-compatible object storage
13+
- **Databases** — managed Postgres, MySQL, Redis
14+
- **Volumes** — persistent block storage attachable to computers
15+
16+
145 tools, exposed via MCP at `https://api.miosa.ai/api/v1/mcp` or locally via `miosa mcp serve`.
17+
18+
## Setup
19+
20+
### Get an API key
21+
22+
```bash
23+
npm install -g @miosa/cli
24+
miosa login
25+
```
26+
27+
Or grab one from `https://miosa.ai/dashboard/api-keys` — format `msk_u_...`.
28+
29+
### Configure MCP
30+
31+
For any MCP-compatible agent (Claude Code, Cursor, Gemini CLI, OSS clients):
32+
33+
```json
34+
{
35+
"mcpServers": {
36+
"miosa": {
37+
"command": "miosa",
38+
"args": ["mcp", "serve"],
39+
"env": { "MIOSA_API_KEY": "msk_..." }
40+
}
41+
}
42+
}
43+
```
44+
45+
Or hit the hosted endpoint directly with `Authorization: Bearer msk_...`.
46+
47+
## Universal conventions
48+
49+
Apply these whether you're using MCP, the REST API, or an SDK:
50+
51+
| Convention | Detail |
52+
|---|---|
53+
| **IDs** | Every tool takes `<resource>_id` first. `create_sandbox` returns one; reuse it. |
54+
| **Status** | Poll `<resource>_get` until `status: "running"`. Never `active`. |
55+
| **Sizes** | xs(1/2GB), small(2/4GB), medium(4/8GB), large(8/16GB), xl(16/32GB). Default `small`. |
56+
| **Paths** | Writable inside VMs: `/workspace` (default cwd), `/home`, `/root`, `/tmp`, `/opt`, `/srv` |
57+
| **Timeouts** | `exec` default 30s. Pass `timeout_ms: 120000` for `npm install` / `pip install`. |
58+
| **Screenshots** | PNG 1024×768. Coordinates absolute pixels, (0,0) top-left. |
59+
60+
## The 5 core workflows
61+
62+
### Run code
63+
64+
```
65+
create_sandbox → exec → read output → destroy_sandbox
66+
```
67+
68+
### Automate a desktop
69+
70+
```
71+
computer_create → desktop_screenshot → desktop_click/type → desktop_screenshot → repeat
72+
```
73+
74+
### Deploy from git
75+
76+
```
77+
deployment_create(repo_url) → deployment_env_set → deployment_publish
78+
```
79+
80+
### Store and share files
81+
82+
```
83+
storage_bucket_create → storage_object_upload → storage_presign (returns public URL)
84+
```
85+
86+
### Provision a database
87+
88+
```
89+
database_create(engine="postgres") → database_credentials → use connection string
90+
```
91+
92+
## Decision tree
93+
94+
```
95+
Need a screen / browser / GUI?
96+
YES → computer
97+
NO ↓
98+
99+
Need to run code or build something?
100+
YES → sandbox
101+
NO ↓
102+
103+
Deploying from GitHub?
104+
YES → deployment
105+
NO ↓
106+
107+
Need to store files?
108+
YES → storage (bucket + presign)
109+
NO ↓
110+
111+
Need a database?
112+
YES → database
113+
```
114+
115+
## Tool catalog (145 tools)
116+
117+
All MCP tool names use `snake_case`. REST endpoints mirror them.
118+
119+
### Sandbox (18)
120+
`create_sandbox`, `get_sandbox`, `list_sandboxes`, `destroy_sandbox`, `sandbox_pause`, `sandbox_resume`, `exec`, `exec_python`, `sandbox_write_file`, `sandbox_read_file`, `sandbox_list_files`, `sandbox_expose`, `sandbox_deploy`, `sandbox_logs`, `sandbox_snapshot_create`, `sandbox_snapshot_list`, `sandbox_snapshot_restore`, `sandbox_template_list`
121+
122+
### Computer (~50)
123+
Lifecycle: `computer_create`, `computer_get`, `computer_list`, `computer_destroy`, `computer_start`, `computer_stop`, `computer_restart`, `computer_update`, `computer_wait`
124+
125+
Desktop input: `desktop_screenshot`, `desktop_click`, `desktop_double_click`, `desktop_type`, `desktop_key`, `desktop_scroll`, `desktop_move_cursor`, `computer_right_click`, `computer_drag`, `computer_hotkey`, `computer_mouse_down`, `computer_mouse_up`, `computer_key_down`, `computer_key_up`
126+
127+
Screen: `computer_get_screen_size`, `computer_get_cursor_position`, `computer_get_clipboard`, `computer_set_clipboard`
128+
129+
Windows: `computer_windows`, `computer_focus_window`, `computer_maximize_window`, `computer_minimize_window`, `computer_close_window`, `computer_set_window_size`, `computer_set_window_position`
130+
131+
Files & shell: `computer_bash`, `computer_write_file`, `computer_read_file`, `computer_list_files`, `computer_stat_file`, `computer_mkdir`, `computer_rename_file`, `computer_copy_file`, `computer_delete_file`
132+
133+
Apps & env: `computer_launch`, `computer_get_desktop_env`, `computer_set_wallpaper`, `computer_accessibility_tree`
134+
135+
Checkpoints: `computer_checkpoint_create`, `computer_checkpoint_list`, `computer_checkpoint_restore`, `computer_checkpoint_delete`
136+
137+
Services: `computer_service_create`, `computer_service_list`, `computer_service_start`, `computer_service_stop`, `computer_service_restart`, `computer_service_logs`, `computer_service_delete`
138+
139+
Env & networking: `computer_env_list`, `computer_env_set`, `computer_env_delete`, `computer_logs`, `computer_domain_add`, `computer_domain_list`, `computer_domain_delete`
140+
141+
### Deploy (13)
142+
`deployment_create`, `deployment_list`, `deployment_get`, `deployment_delete`, `deployment_publish`, `deployment_rollback`, `deployment_env_list`, `deployment_env_set`, `deployment_logs`, `deployment_version_list`, `deployment_version_promote`
143+
144+
### Storage (8)
145+
`storage_bucket_create`, `storage_bucket_list`, `storage_bucket_delete`, `storage_object_upload`, `storage_object_download`, `storage_object_list`, `storage_object_delete`, `storage_presign`
146+
147+
### Database (6)
148+
`database_create`, `database_list`, `database_get`, `database_delete`, `database_credentials`, `database_logs`
149+
150+
### Volume (5)
151+
`volume_create`, `volume_list`, `volume_attach`, `volume_detach`, `volume_delete`
152+
153+
### Workspace (6)
154+
`workspace_create`, `workspace_list`, `workspace_get`, `workspace_update`, `workspace_stats`, `workspace_usage`
155+
156+
### Cron (6)
157+
`cron_create`, `cron_list`, `cron_pause`, `cron_resume`, `cron_run_now`, `cron_delete`
158+
159+
### Webhooks (4)
160+
`webhook_create`, `webhook_list`, `webhook_delete`, `webhook_test`
161+
162+
### Functions (4)
163+
`function_create`, `function_list`, `function_invoke`, `function_delete`
164+
165+
### API keys & platform
166+
`api_key_create`, `api_key_list`, `api_key_delete`, `billing_usage`, `billing_plan`, `region_list`
167+
168+
## Error handling
169+
170+
| Error | Cause | Fix |
171+
|---|---|---|
172+
| `not running` | Action on resource that isn't ready | Poll `<resource>_get` until `status: "running"` |
173+
| `not found` | Bad ID | Verify with `<resource>_list` |
174+
| `path outside allowed` | Wrote to restricted path | Use `/workspace`, `/home`, `/tmp` |
175+
| `timeout` | exec exceeded `timeout_ms` | Increase up to 300000 |
176+
| `rate limited` | Too many API calls | Back off 5s |
177+
| OOM killed | Build exceeded RAM | Bump size to medium or larger |
178+
| `Internal error` | Server bug | Retry once; report if persistent |
179+
180+
## SDKs
181+
182+
If you prefer typed clients over raw MCP:
183+
184+
- **Python**: `pip install miosa` — [github.com/Miosa-osa/miosa-python](https://github.com/Miosa-osa/miosa-python)
185+
- **Elixir**: `{:miosa, "~> 1.0"}` — [github.com/Miosa-osa/miosa-elixir](https://github.com/Miosa-osa/miosa-elixir)
186+
- **Node/TypeScript**: `@miosa/cli` includes a programmatic client — [github.com/Miosa-osa/miosa-cli](https://github.com/Miosa-osa/miosa-cli)
187+
188+
All SDKs use the same REST endpoints as the MCP server. Pick whichever feels native.
189+
190+
## Hosted documentation
191+
192+
- Full docs: https://miosa.ai/docs
193+
- MCP guide: https://miosa.ai/docs/guides/mcp
194+
- Quickstart: https://miosa.ai/docs/quickstart
195+
196+
## Repos
197+
198+
- https://github.com/Miosa-osa/miosa-mcp — Python MCP server
199+
- https://github.com/Miosa-osa/miosa-cli — TypeScript CLI + MCP
200+
- https://github.com/Miosa-osa/miosa-skills — Claude Code skills (this repo)
201+
- https://github.com/Miosa-osa/miosa-python — Python SDK
202+
- https://github.com/Miosa-osa/miosa-elixir — Elixir SDK

‎CLAUDE.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# MIOSA for Claude Code
2+
3+
This file teaches Claude Code how to use MIOSA effectively. Drop it in any project's root (or your home directory) and Claude will follow these conventions.
4+
5+
## When you need cloud infrastructure
6+
7+
This project uses MIOSA cloud infrastructure (Firecracker microVMs). The five `miosa-*` skills in `~/.claude/skills/` handle everything — you don't need to memorize the 145 tools.
8+
9+
| User asks for | Use skill |
10+
|---|---|
11+
| Run code, test a script, build something | `miosa-sandbox` |
12+
| Browser automation, GUI, screenshot/click | `miosa-computer` |
13+
| Deploy a web app from GitHub | `miosa-deploy` |
14+
| Database, storage bucket, volume, cron | `miosa-data` |
15+
| General "how do I X with MIOSA" | `miosa-mcp` |
16+
17+
Skills load automatically when their trigger phrases match. You can also invoke directly with `/miosa-sandbox`, etc.
18+
19+
## Core conventions (apply always)
20+
21+
- **Resource IDs** flow through everything: `create_sandbox` returns an ID, pass it to every subsequent call.
22+
- **Status polling**: `running` means ready. Never `active`. Poll `get_sandbox` / `computer_get` / etc.
23+
- **Default sandbox size**: `small` (4GB). Builds need `medium` (8GB) minimum — `small` will OOM on `npm install` of large dependency trees.
24+
- **File paths**: write to `/workspace` (the canonical cwd). Also writable: `/home`, `/root`, `/tmp`, `/opt`, `/srv`. Anything else returns `path outside allowed`.
25+
- **exec timeouts**: default 30s. Always pass `timeout_ms: 120000` for `npm install` or `pip install`.
26+
27+
## Always destroy when done
28+
29+
Sandboxes and computers bill while running. End every workflow with `destroy_sandbox` or `computer_destroy` unless the user explicitly wants the resource kept alive.
30+
31+
```python
32+
try:
33+
id = create_sandbox(...)
34+
# do work
35+
finally:
36+
destroy_sandbox(sandbox_id=id)
37+
```
38+
39+
## The desktop loop (non-negotiable)
40+
41+
For any GUI task:
42+
43+
```
44+
1. desktop_screenshot → see current state
45+
2. visually identify the target
46+
3. desktop_click / desktop_type / desktop_key
47+
4. desktop_screenshot → verify
48+
5. repeat
49+
```
50+
51+
Never click without screenshotting first. Never assume an action worked — verify with a follow-up screenshot.
52+
53+
## Snapshots save real time
54+
55+
If you're about to do an expensive setup (install dependencies, log in to a service, build a project), snapshot afterwards:
56+
57+
```
58+
sandbox_snapshot_create(sandbox_id=id, name="after-deps")
59+
computer_checkpoint_create(computer_id=id, name="logged-in")
60+
```
61+
62+
Next run, restore in ~1s instead of redoing the setup.
63+
64+
## Heredocs beat write_file
65+
66+
Writing many files? A single `exec` with shell heredocs is much faster than N `sandbox_write_file` calls:
67+
68+
```
69+
exec(sandbox_id=id, command="""
70+
mkdir -p /workspace/src
71+
cat > /workspace/src/index.ts << 'EOF'
72+
export const add = (a, b) => a + b
73+
EOF
74+
""")
75+
```
76+
77+
## When asked to deploy
78+
79+
Never deploy without setting env vars first:
80+
81+
```
82+
1. deployment_create(repo_url=...)
83+
2. deployment_env_set(env={...}) # BEFORE publish
84+
3. deployment_publish(deployment_id=id)
85+
4. deployment_logs(deployment_id=id) # watch build
86+
```
87+
88+
If a deploy fails, check `deployment_logs` first. Don't suggest rebuilding without diagnosing.
89+
90+
## Errors are not failures
91+
92+
Many MIOSA errors are recoverable. Follow the table:
93+
94+
| Error | Action |
95+
|---|---|
96+
| `not running` | Wait, then poll `get_sandbox` |
97+
| `envd_timeout` | VM still booting, retry after 5s |
98+
| `timeout` | Increase `timeout_ms` |
99+
| `path outside allowed` | Switch to `/workspace` |
100+
| `OOM` | Recreate with bigger size |
101+
102+
Only escalate to the user for: auth failures, billing/quota errors, persistent `Internal error` after one retry.
103+
104+
## Tools to prefer
105+
106+
When the user could plausibly use either:
107+
108+
- **Sandbox over Computer** unless a screen is genuinely needed (sandbox is faster, cheaper, easier)
109+
- **`sandbox_deploy` over `deployment_create`** when the user already has a working sandbox
110+
- **`storage_presign` over emailing files** when they need to share something
111+
- **`computer_checkpoint_create` over re-running setup** when iterating on browser automation
112+
113+
## When to ask vs when to act
114+
115+
Act without asking:
116+
- Creating a sandbox to run code the user just shared
117+
- Destroying a sandbox after a successful run
118+
- Setting `timeout_ms: 120000` for installs
119+
120+
Ask first:
121+
- Destroying a sandbox/computer the user might want to keep
122+
- Switching from `small` to `large` (cost implication)
123+
- Deploying to production (`deployment_publish`)
124+
- Deleting a database or bucket
125+
126+
## Reference
127+
128+
- Skills repo: https://github.com/Miosa-osa/miosa-skills
129+
- Full docs: https://miosa.ai/docs
130+
- MCP catalog: https://miosa.ai/docs/guides/mcp

0 commit comments

Comments
 (0)