summaryrefslogtreecommitdiffstats
path: root/SHIP_V2.md
diff options
context:
space:
mode:
Diffstat (limited to 'SHIP_V2.md')
-rw-r--r--SHIP_V2.md240
1 files changed, 0 insertions, 240 deletions
diff --git a/SHIP_V2.md b/SHIP_V2.md
deleted file mode 100644
index 7b607cb..0000000
--- a/SHIP_V2.md
+++ /dev/null
@@ -1,240 +0,0 @@
1# Ship v2
2
3**Ship is a deployment tool built for AI agents.**
4
5Agents write code. Ship puts it on the internet. That's it.
6
7## The Problem
8
9AI agents can write code, but deploying it is a mess:
10- Vercel/Railway/Fly require accounts, API tokens, platform-specific config
11- Docker/K8s are overkill for "make this code accessible via URL"
12- Most tools assume a human is reading the output
13
14Agents need: code → URL. Nothing else.
15
16## Ship's Approach
17
18```bash
19ship ./myproject
20# {"status":"ok","url":"https://abc123.example.com","took_ms":4200}
21```
22
23**That's the entire interface.** Point ship at code, get a URL back as JSON.
24
25### Core Principles
26
271. **JSON in, JSON out** — No human-formatted output. No spinners. No emoji. Agents parse JSON.
28
292. **One command** — No workflows. No "init then configure then deploy." One command does everything.
30
313. **Verify or fail** — Every deploy is health-checked. If the app isn't responding, ship returns an error. No silent failures.
32
334. **Self-cleaning** — Deploys can auto-expire. Agents create lots of previews; they shouldn't pile up forever.
34
355. **Zero config** — Point at a directory. Ship figures out if it's static, Docker, or a binary. No config files required.
36
376. **SSH-only** — No accounts. No API tokens. No vendor lock-in. Just SSH access to a VPS.
38
39## Interface
40
41### Deploy
42
43```bash
44ship ./myproject
45ship ./myproject --name myapp
46ship ./myproject --name preview --ttl 24h
47ship ./site --static
48ship ./api --health /healthz
49```
50
51Output:
52```json
53{
54 "status": "ok",
55 "name": "myapp",
56 "url": "https://myapp.example.com",
57 "type": "docker",
58 "took_ms": 4200,
59 "health": {"status": 200, "latency_ms": 45}
60}
61```
62
63### Error
64
65```json
66{
67 "status": "error",
68 "code": "HEALTH_CHECK_FAILED",
69 "message": "GET /healthz returned 503 after 30s",
70 "name": "myapp",
71 "url": "https://myapp.example.com"
72}
73```
74
75### List
76
77```bash
78ship list
79```
80
81```json
82{
83 "status": "ok",
84 "deploys": [
85 {"name": "api", "url": "https://api.example.com", "type": "docker", "running": true},
86 {"name": "preview-x7k", "url": "https://preview-x7k.example.com", "type": "static", "expires": "2024-02-16T18:00:00Z"}
87 ]
88}
89```
90
91### Status / Logs / Remove
92
93```bash
94ship status myapp
95ship logs myapp
96ship logs myapp --lines 100
97ship remove myapp
98```
99
100All return JSON with `{"status": "ok", ...}` or `{"status": "error", "code": "...", ...}`.
101
102## Error Codes
103
104Machine-readable. No guessing.
105
106| Code | Meaning |
107|------|---------|
108| `SSH_FAILED` | Can't connect to VPS |
109| `UPLOAD_FAILED` | File transfer failed |
110| `BUILD_FAILED` | Docker build or compile failed |
111| `DEPLOY_FAILED` | systemd/Caddy setup failed |
112| `HEALTH_CHECK_FAILED` | App not responding |
113| `NOT_FOUND` | App doesn't exist |
114| `CONFLICT` | Name already taken |
115
116## Auto-Detection
117
118Ship looks at the directory and figures out what to do:
119
120| Directory contains | Deploy type |
121|-------------------|-------------|
122| `Dockerfile` | Docker build → systemd service |
123| `index.html` | Static site → Caddy file_server |
124| Single executable | Binary → systemd service |
125| `go.mod` | Go build → systemd service |
126| `package.json` + no Dockerfile | Error: "Add a Dockerfile" |
127
128No config files. No `ship.json`. No `ship init`.
129
130## TTL (Time-To-Live)
131
132Agents create previews. Previews should auto-delete.
133
134```bash
135ship ./site --name pr-123 --ttl 1h
136ship ./site --name pr-123 --ttl 7d
137```
138
139After TTL expires, the deploy is removed automatically. The `expires` field in JSON tells you when.
140
141## Health Checks
142
143Every deploy is verified. Ship waits for the app to respond before returning success.
144
145- Static sites: `GET /` returns 2xx
146- Apps: `GET /` by default, or specify `--health /healthz`
147- Timeout: 30s
148- If health check fails: `{"status": "error", "code": "HEALTH_CHECK_FAILED", ...}`
149
150## Name Generation
151
152No name? Ship generates one.
153
154```bash
155ship ./site
156# {"name": "ship-a1b2c3", "url": "https://ship-a1b2c3.example.com", ...}
157```
158
159Provide a name to get a stable URL:
160
161```bash
162ship ./site --name docs
163# {"name": "docs", "url": "https://docs.example.com", ...}
164```
165
166## Host Setup
167
168One-time setup for a VPS:
169
170```bash
171ship host init user@my-vps.com --domain example.com
172```
173
174```json
175{
176 "status": "ok",
177 "host": "my-vps.com",
178 "domain": "example.com",
179 "installed": ["caddy", "docker", "systemd"]
180}
181```
182
183After this, the host is ready. Ship remembers it.
184
185## Human Output
186
187Humans are an afterthought, but they can use ship too:
188
189```bash
190ship ./site --pretty
191```
192
193```
194✓ Deployed to https://ship-a1b2c3.example.com (4.2s)
195```
196
197Or set globally:
198```bash
199export SHIP_PRETTY=1
200```
201
202## Implementation Phases
203
204### Phase 1: JSON Everything
205- [ ] JSON output on all commands
206- [ ] Structured error codes
207- [ ] Exit codes match error states
208
209### Phase 2: Smart Deploys
210- [ ] Auto-detect project type
211- [ ] Health checks on every deploy
212- [ ] `--ttl` with server-side cleanup
213
214### Phase 3: Zero Friction
215- [ ] `ship ./dir` with no flags (auto name, auto detect)
216- [ ] `ship host init` fully automated
217- [ ] One binary, zero dependencies on client
218
219## Non-Goals
220
221- **Pretty output** — That's what `--pretty` is for
222- **Interactive prompts** — Never. Agents can't answer prompts.
223- **Config files** — Zero config. Detect everything.
224- **Plugin system** — Keep it simple.
225- **Multi-cloud orchestration** — One VPS at a time.
226
227## Success Criteria
228
229Ship is done when an agent can:
230
2311. Build code
2322. Run `ship ./code`
2333. Parse the JSON response
2344. Use the URL
235
236No docs. No setup. No tokens. No accounts. Just `ship ./code`.
237
238---
239
240*Built for agents. Tolerated by humans.*