Skip to content

Commit 439e8e8

Browse files
thisisjofrankthisisjofrank
authored
update sandbox docs as per --help (#2895)
1 parent f70831a commit 439e8e8

File tree

3 files changed

+343
-2
lines changed

3 files changed

+343
-2
lines changed

‎ai/index.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,155 @@ url: /ai/
77
This page is a short entrypoint for LLMs and AI agents consuming the Deno
88
documentation.
99

10+
## Deno overview
11+
12+
Deno is a secure JavaScript and TypeScript runtime built on V8 and Rust that
13+
ships as a single binary with batteries included: TypeScript transpilation,
14+
bundling, formatting, linting, testing, and a rich standard library all work out
15+
of the box. Its explicit permission model (`--allow-net`, `--allow-read`, etc.)
16+
keeps programs sandboxed by default, which is especially useful for AI agents
17+
that need predictable side effects when running untrusted code snippets.
18+
19+
## Usage highlights for agents
20+
21+
### Everything starts with the CLI
22+
23+
Deno is fundamentally a command-line program. Most workflows boil down to
24+
learning a handful of subcommands and flags.
25+
26+
Common starting points:
27+
28+
```
29+
deno run main.ts
30+
deno test
31+
deno fmt
32+
deno lint
33+
deno task <name>
34+
```
35+
36+
### “Secure by default” means you must think about permissions
37+
38+
By default, deno run executes in a sandbox. If code needs the network or
39+
filesystem, you grant it explicitly with --allow-* flags (or accept an
40+
interactive prompt, when applicable).
41+
42+
Example:
43+
44+
```
45+
# Allow network + read access (common for servers that read local files)
46+
deno run --allow-net --allow-read server.ts
47+
48+
# Restrict read access to a specific path
49+
deno run --allow-read=./data main.ts
50+
51+
# Allow everything (convenient for local experiments, not a great default)
52+
deno run -A main.ts
53+
```
54+
55+
### Deno projects are usually centered around deno.json
56+
57+
A deno.json (or deno.jsonc) file configures the runtime and tooling: TypeScript
58+
settings, lint/format behavior, import maps, tasks, and more. Deno will
59+
auto-detect it up the directory tree. Deno also supports package.json and will
60+
run node projects with `deno run` without modification.
61+
62+
Deno projects prefer imports from jsr or npm with the correct specifiers.
63+
64+
Two fields in the deno.json matter constantly:
65+
66+
**Tasks**: lightweight “scripts” you run with deno task:
67+
68+
```
69+
{
70+
"tasks": {
71+
"dev": "deno run --watch --allow-net main.ts",
72+
"test": "deno test",
73+
"lint": "deno lint",
74+
"fmt": "deno fmt"
75+
}
76+
}
77+
```
78+
79+
Tasks are the easiest way to standardize permissions and flags so users don’t
80+
have to remember them.
81+
82+
**Imports**: an import map that lets you use clean “bare specifiers”:
83+
84+
```
85+
{
86+
"imports": {
87+
"@std/assert": "jsr:@std/assert@^1.0.0",
88+
"chalk": "npm:chalk@5"
89+
}
90+
}
91+
```
92+
93+
Then in code:
94+
95+
```
96+
import { assertEquals } from "@std/assert";
97+
import chalk from "chalk";
98+
```
99+
100+
Dependencies can be added with the `deno add` command. Deno uses ES modules and
101+
can import from multiple sources:
102+
103+
- JSR (recommended for many third-party modules and the Deno Standard Library)
104+
- npm packages (native support, without requiring a separate npm install step)
105+
106+
### Node + npm compatibility is real (and has conventions)
107+
108+
Deno can run lots of Node-targeted code, but there are a couple of “Deno-isms”
109+
to know:
110+
111+
Node built-ins are imported with the node: prefix:
112+
113+
```
114+
import * as os from "node:os";
115+
```
116+
117+
npm packages can be imported with an npm: specifier (and often mapped to bare
118+
names via deno.json imports).
119+
120+
This is why Deno can often use npm packages without a traditional install step
121+
or a node_modules workflow.
122+
123+
### Built-in testing, formatting, linting (use them)
124+
125+
Deno’s standard workflow expects you to lean on the CLI:
126+
127+
`deno test` finds and runs tests by convention
128+
129+
`deno fmt` formats code
130+
131+
`deno lint` lints code
132+
133+
**For agents:** when someone asks “how do I run this?” in Deno, the answer is
134+
usually a combination of (a) the right permissions and (b) the right built-in
135+
command.
136+
137+
### Bootstrapping: deno init gets you to a working project fast
138+
139+
To start a project, Deno provides templates via deno init, including library
140+
scaffolding and a simple server setup.
141+
142+
```
143+
deno init my_project
144+
# or
145+
deno init --lib
146+
# or
147+
deno init --serve
148+
```
149+
10150
## Key resources
11151

12152
- [llms-summary.txt](/llms-summary.txt): compact, high-signal index
13153
- [llms.txt](/llms.txt): full section index
14154
- [llms.json](/llms.json): structured index (Orama summary)
15155
- [llms-full.txt](/llms-full.txt): full content dump (large)
16156
- [Site search](/): use the on-site search UI for human browsing
157+
- [Skills](https://github.com/denoland/skills): AI skills build for coding
158+
assistants.
17159

18160
## Usage notes
19161

‎runtime/reference/cli/sandbox.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,202 @@ openGraphLayout: "/open_graph/cli-commands.jsx"
55
openGraphTitle: "deno sandbox"
66
description: "Spin up a secure Linux microVM"
77
---
8+
9+
The `deno sandbox` command allows you to spin up a secure Linux microVM,
10+
designed for running untrusted code in a sandboxed environment. See the
11+
[Sandbox documentation](/sandbox/cli/) for more detailed examples of usage.
12+
13+
## Authentication
14+
15+
In order to use the `deno sandbox` command, you need to have a Deno Deploy
16+
account and a valid authentication token. Follow the instructions in the
17+
[Getting started with Deno Sandbox](/sandbox/getting_started/) documentation.
18+
19+
## Global options
20+
21+
- `-h`, `--help` - Show this help.
22+
- `--token` <token> - Auth token to use
23+
- `--config` <config> - Path for the config file
24+
- `--org` <name> - The name of the organization
25+
26+
## Subcommands
27+
28+
### Create a new sandbox
29+
30+
Creates a new sandbox in an organization. Accepts the aliases `create` and
31+
`new`.
32+
33+
```bash
34+
deno sandbox create
35+
```
36+
37+
### List your sandboxes
38+
39+
Lists all sandboxes in an organization. Accepts the aliases `list` and `ls`.
40+
41+
```bash
42+
deno sandbox list
43+
```
44+
45+
### Kill a sandbox
46+
47+
Terminates a running sandbox immediately. Accepts the aliases `kill`, `remove`,
48+
and `rm`.
49+
50+
```bash
51+
deno sandbox kill <sandbox-id>
52+
```
53+
54+
### Copy files
55+
56+
Copies files between your local machine and a running sandbox. Use `copy` or its
57+
shorter alias `cp`.
58+
59+
```bash
60+
deno sandbox copy <paths...>
61+
```
62+
63+
### Execute a command
64+
65+
Runs an arbitrary command inside an existing sandbox.
66+
67+
```bash
68+
deno sandbox exec <sandbox-id> <command...>
69+
```
70+
71+
Example:
72+
73+
```bash
74+
deno sandbox exec sbx-1234 uptime
75+
```
76+
77+
### Extend timeout
78+
79+
Extends how long a sandbox stays active before timing out.
80+
81+
```bash
82+
deno sandbox extend <sandbox-id> <timeout>
83+
```
84+
85+
Accepts time durations in the format of a number followed by a unit, where the
86+
unit can be `s` for seconds, `m` for minutes, or `h` for hours.
87+
88+
Example:
89+
90+
```bash
91+
deno sandbox extend <sandbox-id> 30m
92+
```
93+
94+
### SSH into a sandbox
95+
96+
Opens an interactive SSH session to the sandbox.
97+
98+
```bash
99+
deno sandbox ssh <sandbox-id>
100+
```
101+
102+
### Deploy a sandbox
103+
104+
Turns the state of a running sandbox into a Deno Deploy application.
105+
106+
```bash
107+
deno sandbox deploy <sandbox-id> <app>
108+
```
109+
110+
### Manage volumes
111+
112+
Creates, lists, and attaches persistent block volumes.
113+
114+
```bash
115+
deno sandbox volumes --help
116+
```
117+
118+
#### Create a volume
119+
120+
Creates a new volume. Accepts the alias `volumes create` or `volumes new`.
121+
122+
```bash
123+
deno sandbox volumes create <name>
124+
```
125+
126+
#### List volumes
127+
128+
Lists all volumes in an organization. Accepts the alias `volumes list` or
129+
`volumes ls`.
130+
131+
```bash
132+
deno sandbox volumes list
133+
```
134+
135+
#### Delete a volume
136+
137+
Deletes a volume. Accepts the alias `volumes delete`, `volumes rm` or
138+
`volumes remove`.
139+
140+
```bash
141+
deno sandbox volumes delete <volume-id-or-slug>
142+
```
143+
144+
or
145+
146+
```bash
147+
deno sandbox volumes delete <volume-slug>
148+
```
149+
150+
#### Snapshot a volume
151+
152+
Creates a snapshot of a volume. Accepts a volume ID or slug and a snapshot slug
153+
154+
```bash
155+
deno sandbox volumes snapshot <volume-id-or-slug> <snapshot-slug>
156+
```
157+
158+
or
159+
160+
```bash
161+
deno sandbox volumes snapshot <volume-slug> <snapshot-slug>
162+
```
163+
164+
### Manage snapshots
165+
166+
Creates and restores filesystem snapshots for sandboxes.
167+
168+
```bash
169+
deno sandbox snapshots --help
170+
```
171+
172+
#### Create a snapshot
173+
174+
Creates a new snapshot of a sandbox. Accepts the alias `snapshots create` or
175+
`snapshots new`. It requires a volume ID or volume slug and a snapshot slug.
176+
177+
```bash
178+
deno sandbox snapshots create <volume-id-or-slug> <snapshot-slug>
179+
```
180+
181+
#### List snapshots
182+
183+
Lists all snapshots in an organization. Accepts the alias `snapshots list` or
184+
`snapshots ls`.
185+
186+
```bash
187+
deno sandbox snapshots list
188+
```
189+
190+
#### Delete a snapshot
191+
192+
Deletes a snapshot. Accepts the alias `snapshots delete`, `snapshots rm` or
193+
`snapshots remove`. It requires a snapshot ID or snapshot slug.
194+
195+
```bash
196+
deno sandbox snapshots delete <id-or-slug>
197+
```
198+
199+
### Switch organizations or apps
200+
201+
Switches your current Deploy organization or application context, which the
202+
sandbox command uses for authentication.
203+
204+
```bash
205+
deno sandbox switch
206+
```

‎sandbox/_data.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,8 @@ export const sidebar = [
6060
href: "https://console.deno.com/api/v2/docs",
6161
},
6262
{
63-
title: "CLI subcommand",
64-
href: "/runtime/reference/cli/deploy/#sandbox-management",
63+
title: "Sandbox CLI commands",
64+
href: "/runtime/reference/cli/sandbox/",
6565
},
6666
{
6767
title: "Examples",

0 commit comments

Comments
 (0)