@stateset/sandbox-cli 1.0.5 → 1.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +221 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# @stateset/sandbox-cli
|
|
2
|
+
|
|
3
|
+
Command-line interface for managing [StateSet Sandbox](https://github.com/stateset/stateset-sandbox) environments — create sandboxes, manage checkpoints, upload artifacts, orchestrate agent sessions, and more.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @stateset/sandbox-cli
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Requires Node.js >= 20.
|
|
12
|
+
|
|
13
|
+
## Quick Start
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
# Interactive setup — prompts for API key, URL, and defaults
|
|
17
|
+
stateset config setup
|
|
18
|
+
|
|
19
|
+
# Or configure manually
|
|
20
|
+
stateset config set-key sk_live_your_api_key
|
|
21
|
+
stateset config set-url https://api.stateset.com
|
|
22
|
+
|
|
23
|
+
# Create a sandbox and run a command
|
|
24
|
+
stateset sandbox create --timeout 600
|
|
25
|
+
stateset sandbox exec <sandbox-id> "echo hello world"
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Configuration
|
|
29
|
+
|
|
30
|
+
The CLI stores configuration locally via [conf](https://github.com/sindresorhus/conf). Environment variables take precedence over stored values.
|
|
31
|
+
|
|
32
|
+
| Setting | Env Variable | Default |
|
|
33
|
+
|---------|-------------|---------|
|
|
34
|
+
| API Key | `STATESET_API_KEY` | — |
|
|
35
|
+
| API URL | `STATESET_API_URL` | `http://localhost:8080` |
|
|
36
|
+
| Default Timeout | `STATESET_DEFAULT_TIMEOUT_SECONDS` | `300` |
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
stateset config show # Display current configuration
|
|
40
|
+
stateset config path # Show config file location
|
|
41
|
+
stateset config clear # Wipe all stored config
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Commands
|
|
45
|
+
|
|
46
|
+
### `stateset sandbox`
|
|
47
|
+
|
|
48
|
+
Manage sandbox environments.
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
stateset sandbox create [options] # Create a new sandbox
|
|
52
|
+
stateset sandbox list # List all sandboxes
|
|
53
|
+
stateset sandbox get <id> # Get sandbox details
|
|
54
|
+
stateset sandbox exec <id> <command> # Execute a command
|
|
55
|
+
stateset sandbox stop <id> # Stop a sandbox
|
|
56
|
+
stateset sandbox extend <id> # Extend sandbox lifetime
|
|
57
|
+
stateset sandbox write <id> <path> <content> # Write a file
|
|
58
|
+
stateset sandbox read <id> <path> # Read a file
|
|
59
|
+
stateset sandbox ls-files <id> # List directory contents
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**Create options:**
|
|
63
|
+
|
|
64
|
+
| Flag | Description | Example |
|
|
65
|
+
|------|-------------|---------|
|
|
66
|
+
| `-t, --timeout <seconds>` | Sandbox timeout | `--timeout 600` |
|
|
67
|
+
| `-c, --cpus <cpus>` | CPU limit | `--cpus 1` |
|
|
68
|
+
| `-m, --memory <memory>` | Memory limit | `--memory 1Gi` |
|
|
69
|
+
| `-i, --isolation <level>` | Isolation level | `--isolation gvisor` |
|
|
70
|
+
| `-e, --env <KEY=VALUE>` | Environment variables (repeatable) | `-e FOO=bar -e BAZ=qux` |
|
|
71
|
+
|
|
72
|
+
### `stateset checkpoint`
|
|
73
|
+
|
|
74
|
+
Create, restore, and compare sandbox checkpoints.
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
stateset checkpoint create <sandbox-id> <name> # Create checkpoint
|
|
78
|
+
stateset checkpoint list # List checkpoints
|
|
79
|
+
stateset checkpoint get <id> # Get details
|
|
80
|
+
stateset checkpoint restore <sandbox-id> <cp-id> # Restore checkpoint
|
|
81
|
+
stateset checkpoint clone <id> <new-name> # Clone a checkpoint
|
|
82
|
+
stateset checkpoint diff <id-1> <id-2> # Compare two checkpoints
|
|
83
|
+
stateset checkpoint rm <id> # Delete checkpoint
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**Create options:** `--description`, `--include <paths>`, `--exclude <paths>`, `--no-env`
|
|
87
|
+
**Restore options:** `--no-files`, `--no-env`, `--no-overwrite`
|
|
88
|
+
|
|
89
|
+
### `stateset artifact`
|
|
90
|
+
|
|
91
|
+
Upload, download, and manage sandbox artifacts.
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
stateset artifact upload <sandbox-id> <path> # Upload artifact
|
|
95
|
+
stateset artifact list # List artifacts
|
|
96
|
+
stateset artifact get <id> # Get details
|
|
97
|
+
stateset artifact url <id> # Get download URL
|
|
98
|
+
stateset artifact download <sandbox-id> <id> <path> # Download artifact
|
|
99
|
+
stateset artifact rm <id> # Delete artifact
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
**Upload options:** `--type <content-type>`, `--expires <seconds>`, `--metadata <key=value>`
|
|
103
|
+
|
|
104
|
+
### `stateset session`
|
|
105
|
+
|
|
106
|
+
Orchestrate long-running agent sessions with budget controls.
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
stateset session create [options] # Create agent session
|
|
110
|
+
stateset session list # List sessions
|
|
111
|
+
stateset session get <id> # Get session details
|
|
112
|
+
stateset session start <id> # Start session
|
|
113
|
+
stateset session pause <id> # Pause session
|
|
114
|
+
stateset session resume <id> # Resume session
|
|
115
|
+
stateset session stop <id> # Stop gracefully
|
|
116
|
+
stateset session cancel <id> # Cancel immediately
|
|
117
|
+
stateset session exec <id> <command> # Execute in session
|
|
118
|
+
stateset session events <id> # List session events
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**Create options:**
|
|
122
|
+
|
|
123
|
+
| Flag | Description |
|
|
124
|
+
|------|-------------|
|
|
125
|
+
| `-n, --name <name>` | Session name |
|
|
126
|
+
| `-d, --description <desc>` | Description |
|
|
127
|
+
| `--cost-cap <cents>` | Cost cap in cents (e.g., 500 = $5) |
|
|
128
|
+
| `--iteration-limit <n>` | Max iterations |
|
|
129
|
+
| `--duration-limit <seconds>` | Max duration |
|
|
130
|
+
| `--cpus <cpus>` | CPU allocation (default: 2) |
|
|
131
|
+
| `--memory <memory>` | Memory allocation (default: 4Gi) |
|
|
132
|
+
|
|
133
|
+
### `stateset tunnel`
|
|
134
|
+
|
|
135
|
+
Expose sandbox services via tunnels.
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
stateset tunnel open <sandbox-id> # Create tunnel (default port 8080)
|
|
139
|
+
stateset tunnel list <sandbox-id> # List active tunnels
|
|
140
|
+
stateset tunnel close <tunnel-id> # Close tunnel
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**Open options:** `-p, --port <port>`, `--protocol <http|https>`, `--expires-in <seconds>`
|
|
144
|
+
|
|
145
|
+
### `stateset pool`
|
|
146
|
+
|
|
147
|
+
Monitor the warm pod pool.
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
stateset pool stats # Get pool statistics
|
|
151
|
+
stateset pool watch # Watch stats in real-time
|
|
152
|
+
stateset pool watch --interval 2 # Custom refresh interval
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### `stateset deploy`
|
|
156
|
+
|
|
157
|
+
Deploy to Kubernetes via cloud provider overlays.
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
stateset deploy aws # Deploy AWS overlay
|
|
161
|
+
stateset deploy gcp --dry-run # Dry-run GCP overlay
|
|
162
|
+
stateset deploy azure --preflight --wait # Full deploy with checks
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
**Options:** `--kubeconfig`, `--context`, `--namespace`, `--dry-run`, `--preflight`, `--wait`, `--smoke`, `--post-check`
|
|
166
|
+
|
|
167
|
+
### `stateset doctor`
|
|
168
|
+
|
|
169
|
+
Diagnose CLI configuration and API connectivity.
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
stateset doctor # Basic health check
|
|
173
|
+
stateset doctor --full # Deep diagnostics
|
|
174
|
+
stateset doctor --cluster # Include Kubernetes checks
|
|
175
|
+
stateset doctor --api # Check dashboard endpoints
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### `stateset health`
|
|
179
|
+
|
|
180
|
+
Platform-wide health snapshot.
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
stateset health # Quick platform status
|
|
184
|
+
stateset health --grade # Include readiness grade
|
|
185
|
+
stateset health --cluster # Include Kubernetes checks
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### `stateset grade`
|
|
189
|
+
|
|
190
|
+
Compute platform readiness grade (A+ through F).
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
stateset grade # Compute grade
|
|
194
|
+
stateset grade --minimum A- # Fail if below A-
|
|
195
|
+
stateset grade --cluster --json # Full check, JSON output
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## JSON Output
|
|
199
|
+
|
|
200
|
+
Most commands support `--json` for machine-readable output, useful for scripting:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
stateset sandbox list --json | jq '.[0].id'
|
|
204
|
+
stateset pool stats --json
|
|
205
|
+
stateset grade --json
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
## Development
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
cd cli
|
|
212
|
+
npm install
|
|
213
|
+
npm run dev -- sandbox list # Run locally via tsx
|
|
214
|
+
npm run build # Compile TypeScript
|
|
215
|
+
npm test # Run tests
|
|
216
|
+
npm run typecheck # Type-check without emitting
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
## License
|
|
220
|
+
|
|
221
|
+
MIT
|