Skip to content

Commit 8c4fb53

Browse files
BhautikChudasamaBhautikChudasama
committed
docs: updated README
1 parent 5b03229 commit 8c4fb53

3 files changed

Lines changed: 126 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 123 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -288,6 +288,70 @@ Sensitive and noisy files are always excluded: `.env`, `.env.*`, secrets/keys (`
288288
| `createos vms resize` | Resize a VM to a different plan |
289289
| `createos vms terminate` | Permanently destroy a VM |
290290

291+
### Sandboxes
292+
293+
Sandboxes are fast-booting VMs — isolated environments you can exec into, sync files to, tunnel ports through, and snapshot at will.
294+
295+
| Command | Description |
296+
| ---------------------------------- | ------------------------------------------------------------- |
297+
| `createos sandbox create` | Create a new sandbox |
298+
| `createos sandbox list` | List your sandboxes |
299+
| `createos sandbox get` | Show details for one sandbox |
300+
| `createos sandbox edit` | Change a sandbox's settings (public URL, SSH keys, auto-pause)|
301+
| `createos sandbox pause` | Snapshot a running sandbox so you can resume it later |
302+
| `createos sandbox resume` | Bring a paused sandbox back to life |
303+
| `createos sandbox fork` | Clone a paused sandbox into a brand-new one |
304+
| `createos sandbox rm` | Delete one or more sandboxes |
305+
| `createos sandbox exec` | Run a command inside a sandbox |
306+
| `createos sandbox shell` | Open an interactive shell inside a sandbox |
307+
| `createos sandbox sync` | Two-way file sync between your laptop and a sandbox |
308+
| `createos sandbox push` | Copy a local file into a sandbox |
309+
| `createos sandbox pull` | Copy a file out of a sandbox |
310+
| `createos sandbox tunnel` | Forward a local port to a port inside a sandbox |
311+
| `createos sandbox shapes` | List available sandbox sizes (vCPU / RAM / disk) |
312+
| `createos sandbox rootfs` | List built-in OS images you can boot a sandbox from |
313+
314+
**`sandbox create` flags:**
315+
316+
| Flag | Description |
317+
| --------------- | -------------------------------------------------------------------------------- |
318+
| `--shape` | Size of the sandbox (see `createos sandbox shapes`) |
319+
| `--name` | Friendly name for the sandbox |
320+
| `--rootfs` | Base image or custom template to start from |
321+
| `--disk-mib` | Disk size in MiB (defaults to the shape's standard disk) |
322+
| `--ssh-key` | Path to an SSH public key file (repeatable) |
323+
| `--env` | Environment variable for every exec (repeatable): `KEY=VALUE` |
324+
| `--egress` | Allowed outbound host/IP (repeatable). Empty = unrestricted. |
325+
| `--network` | Private network to join at creation (repeatable): `<name\|id>` |
326+
| `--disk` | S3 disk to mount at creation (repeatable): `<name\|id>:/mount/path` |
327+
| `--ingress` | Give the sandbox a public HTTPS URL |
328+
| `--auto-pause` | Auto-pause after inactivity (e.g. `10m`, `1h`). Omit to keep running. |
329+
330+
**Sandbox sub-resource commands:**
331+
332+
| Command | Description |
333+
| ---------------------------------------------- | -------------------------------------------------------- |
334+
| `createos sandbox disk create` | Register an S3 bucket as a mountable disk |
335+
| `createos sandbox disk ls` | List your disks |
336+
| `createos sandbox disk show <name\|id>` | Show details for one disk |
337+
| `createos sandbox disk attach <sb> <disk> <path>` | Mount a disk into a running sandbox |
338+
| `createos sandbox disk detach <sb> <disk> <path>` | Unmount a disk from a sandbox |
339+
| `createos sandbox disk rm <name\|id>` | Delete a disk (auto-detaches first) |
340+
| `createos sandbox network create <name>` | Create a private network |
341+
| `createos sandbox network ls` | List your networks |
342+
| `createos sandbox network show <name\|id>` | Show a network and its attached sandboxes |
343+
| `createos sandbox network attach <sb> <net>` | Add a sandbox to a network |
344+
| `createos sandbox network detach <sb> <net>` | Remove a sandbox from a network |
345+
| `createos sandbox network rm <name\|id>` | Delete a network (auto-detaches first) |
346+
| `createos sandbox firewall show <sandbox>` | Show what the sandbox is allowed to reach |
347+
| `createos sandbox firewall set <sb> <host…>` | Replace the outbound allowlist |
348+
| `createos sandbox firewall clear <sandbox>` | Open the firewall — allow all outbound traffic |
349+
| `createos sandbox template submit <name>` | Build a Dockerfile into a sandbox image |
350+
| `createos sandbox template ls` | List your custom sandbox images |
351+
| `createos sandbox template show <name\|id>` | Show details for one image |
352+
| `createos sandbox template logs <name\|id>` | Show (or follow) the build output for an image |
353+
| `createos sandbox template rm <name\|id>` | Delete a custom image |
354+
291355
### Skills
292356

293357
| Command | Description |
@@ -407,6 +471,58 @@ createos cronjobs update --project <id> --cronjob <id> \
407471
createos cronjobs get --project <id> --cronjob <id>
408472
createos cronjobs delete --project <id> --cronjob <id> --force
409473

474+
# Sandboxes
475+
createos sandbox create --shape s-1vcpu-1gb --name my-box --ssh-key ~/.ssh/id_ed25519.pub
476+
createos sandbox create --shape s-1vcpu-512mb --ingress --auto-pause 1h
477+
createos sandbox list
478+
createos sandbox list --all
479+
createos sandbox list --status paused --quiet | xargs createos sandbox rm --force
480+
createos sandbox get <id>
481+
createos sandbox exec my-box -- uname -a
482+
createos sandbox exec my-box --stream -- pip install requests
483+
createos sandbox shell my-box
484+
createos sandbox shell my-box --ssh
485+
createos sandbox push my-box ./script.py /root/script.py
486+
createos sandbox pull my-box /root/output.csv ./output.csv
487+
createos sandbox tunnel my-box --local 8080 --remote 8000
488+
createos sandbox pause my-box
489+
createos sandbox resume my-box
490+
createos sandbox fork my-box
491+
createos sandbox edit my-box --ingress on
492+
createos sandbox edit my-box --auto-pause 30m
493+
createos sandbox rm my-box --force
494+
createos sandbox shapes
495+
createos sandbox rootfs
496+
497+
# Sandbox sync
498+
createos sandbox sync my-box --local ~/work/project --remote /root/work
499+
500+
# Sandbox disks
501+
createos sandbox disk create my-data --bucket my-bucket --endpoint https://s3.amazonaws.com \
502+
--access-key AKID... --secret-key ...
503+
createos sandbox disk ls
504+
createos sandbox disk attach my-box my-data /mnt/data
505+
createos sandbox disk detach my-box my-data /mnt/data --yes
506+
createos sandbox disk rm my-data --yes
507+
508+
# Sandbox networks
509+
createos sandbox network create my-net
510+
createos sandbox network ls
511+
createos sandbox network attach my-box my-net
512+
createos sandbox network detach my-box my-net --yes
513+
createos sandbox network rm my-net --yes
514+
515+
# Sandbox firewall
516+
createos sandbox firewall show my-box
517+
createos sandbox firewall set my-box pypi.org github.com
518+
createos sandbox firewall clear my-box --yes
519+
520+
# Sandbox templates (custom images)
521+
createos sandbox template submit my-rails -f Dockerfile
522+
createos sandbox template ls
523+
createos sandbox template logs my-rails --follow
524+
createos sandbox template rm my-rails --yes
525+
410526
# Templates
411527
createos templates use --template <id> --yes
412528

@@ -455,11 +571,13 @@ createos environments list --project <id> -o json
455571

456572
## Options
457573

458-
| Flag | Description |
459-
| --------------------- | -------------------------------------------------------------------- |
460-
| `--output, -o <fmt>` | Output format: `json` or `table` (default). Auto-json when piped. |
461-
| `--debug, -d` | Print HTTP request/response details (token is masked) |
462-
| `--api-url` | Override the API base URL |
574+
| Flag | Description |
575+
| ------------------------ | -------------------------------------------------------------------- |
576+
| `--output, -o <fmt>` | Output format: `json` or `table` (default). Auto-json when piped. |
577+
| `--debug, -d` | Print HTTP request/response details (token is masked) |
578+
| `--api-url` | Override the API base URL |
579+
| `--sandbox-api-url` | Override the sandbox (fc-spawn) base URL |
580+
| `--sandbox-gateway` | SSH gateway address (`host:port`) used by `sandbox shell --ssh` |
463581

464582
## Security
465583

‎cmd/root/root.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ func NewApp() *cli.App {
6767
Name: "sandbox-gateway",
6868
Usage: "SSH gateway address (<host:port>) used by `sandbox shell`",
6969
EnvVars: []string{"CREATEOS_SANDBOX_GATEWAY"},
70-
Value: "65.109.104.247:2222",
70+
Value: "gateway.sb.createos.sh:2222",
7171
},
7272
&cli.StringFlag{
7373
Name: "output",

‎internal/api/sandbox_client.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import (
88
// sandbox surface lives on a different host from the main CreateOS API
99
// (api-createos.nodeops.network); these two clients are wired
1010
// side-by-side under app.Metadata.
11-
const DefaultSandboxBaseURL = "https://fc-spawn.bhautik.in"
11+
const DefaultSandboxBaseURL = "https://api.sb.createos.sh"
1212

1313
// SandboxClient wraps a resty.Client configured for the fc-spawn API.
1414
// Mirrors APIClient but targets the sandbox base URL and uses
@@ -72,4 +72,4 @@ func newSandboxClient(authHeader, token, sandboxURL string, debug bool, refreshe
7272
}
7373

7474
// SandboxClientKey is the cli.Context metadata key for the sandbox client.
75-
const SandboxClientKey = "sandbox_client"
75+
const SandboxClientKey = "sandbox_client" // #nosec G101 -- context metadata key, not a credential // pragma: allowlist secret

0 commit comments

Comments
 (0)