From f0ab216f91be92066cba1b604c315499333f70da Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 17:26:31 +0000 Subject: [PATCH 01/15] Rewrite and publish Networking concept page for rc44 --- src/content/docs/concepts/networking.mdx | 281 ++++++----------------- src/lib/sidebar.ts | 1 + 2 files changed, 71 insertions(+), 211 deletions(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 1bd510b..9cf4f8d 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -1,266 +1,125 @@ --- title: Networking -description: HTTP access, URLs, port forwarding, and network configuration -draft: true +description: How traffic reaches a Sprite and how a Sprite reaches out. The URL and proxy that get you in, and the egress policy that governs what goes out +publishedDate: 2026-07-08 +author: kcmartin --- -import { Tabs, TabItem } from '@astrojs/starlight/components'; -import { Snippet, LinkCard, CardGrid } from '@/components/react'; +import { Callout, LinkCard, CardGrid } from '@/components/react'; -Sprites run your code in the cloud. This page is about how to talk to that code via HTTPS URLs and port forwarding that make remote services feel local. You get a public endpoint to hit your app over the Internet, and the ability to proxy ports straight to your laptop so you can test, debug, and connect tools like you're running everything on localhost. +A Sprite runs your code in the cloud, but it's meant to feel close. There are two ways traffic gets in, an always-on HTTPS URL and a proxy that maps a remote port onto your laptop, and one policy that governs what the Sprite can reach on its way out. This page is the model for all three. The exact commands live on the pages linked throughout. -## Sprite URLs +## Reaching a Sprite -Every Sprite has a unique URL for HTTPS access, for example: +Inbound traffic arrives one of two ways, and which you pick depends on whether you want a public endpoint or a local one. -```bash -sprite url -``` - -```output -https://my-sprite-abc123.sprites.app -``` - -If your code is listening on a port (say, 3000 or 8080), that URL routes traffic to it. This means you can: - -- Access web applications running in your Sprite -- Test a dev server in the cloud -- Make API requests to services -- Connect services to each other via HTTP - -### URL Authentication - -By default, Sprite URLs are private and they require a valid token. You can make them public if you want to share a demo, open up a webhook, or quickly put something onto the Internet: - - - -```bash -# Make URL public (no authentication required) - good for webhooks, public APIs, demos -sprite url update --auth public - -# Require sprite authentication (default) - good for internal services, development -sprite url update --auth default -``` - - - -```javascript -// Get sprite info including URL -const info = await client.getSprite('my-sprite'); -console.log(info.url); -``` - - - -Updating URL settings is available via the CLI, Go SDK, or REST API (the JS SDK does not expose a helper yet). +- **The Sprite URL** is always on and needs no CLI. Every Sprite has one at `https://-.sprites.dev/`, and it routes HTTPS to the Sprite's HTTP service. It's the way to reach an app over the Internet: a webhook target, a shared demo, an API. It carries HTTP(S) to a single port. +- **`sprite proxy`** maps a remote port onto your machine so the Sprite feels local. It forwards any TCP protocol, not just HTTP, which is how you point a database client or a browser at a service running in the Sprite. It's local to your machine, not the Internet, and it only runs while the CLI does. -## Port Forwarding - -Here's the trick that makes Sprites feel local: port forwarding. - -Now your laptop's localhost:3000 forwards to the Sprite's port 3000. You can open a browser, curl it, or connect with tools that expect a local port. - -Try these examples: - - - ```bash -# Forward local port 3000 to sprite port 3000 -sprite proxy 3000 - -# Forward multiple ports -sprite proxy 3000 8080 5432 - -# Now access locally -curl http://localhost:3000 -``` - - - -```go -// Forward single port -session, err := client.ProxyPort(ctx, "my-sprite", 3000, 3000) -if err != nil { - log.Fatal(err) -} -defer session.Close() - -// localhost:3000 now forwards to sprite:3000 -fmt.Println("Proxy active at localhost:3000") - -// Forward multiple ports -sessions, err := client.ProxyPorts(ctx, "my-sprite", []sprites.PortMapping{ - {LocalPort: 3000, RemotePort: 3000}, - {LocalPort: 8080, RemotePort: 80}, - {LocalPort: 5432, RemotePort: 5432}, -}) -defer func() { - for _, s := range sessions { - s.Close() - } -}() -``` - - - -```elixir -# Forward single port -{:ok, session} = Sprites.proxy_port(sprite, 3000, 3000) - -# localhost:3000 now forwards to sprite:3000 -IO.puts("Proxy active at localhost:3000") - -# Forward multiple ports -mappings = [ - %Sprites.Proxy.PortMapping{local_port: 3000, remote_port: 3000}, - %Sprites.Proxy.PortMapping{local_port: 8080, remote_port: 80}, - %Sprites.Proxy.PortMapping{local_port: 5432, remote_port: 5432} -] -{:ok, sessions} = Sprites.proxy_ports(sprite, mappings) - -# Stop proxy when done -Sprites.Proxy.Session.stop(session) -``` - - - -Port forwarding works for TCP services — web servers, databases, message brokers, whatever. It's just sockets. - -## Real-World Examples - -### Starting a Web Server - -Run a web server and access it via the Sprite URL: - -```bash -# Start a simple HTTP server -sprite exec -detachable "python -m http.server 8080" - -# Get the URL +# Always-on HTTPS to the Sprite's HTTP service sprite url -``` -```output -https://my-sprite-abc123.sprites.app -``` - -```bash -# Access via browser or curl (after making public) -curl https://my-sprite-abc123.sprites.app:8080/ +# Map the Sprite's port 5432 onto localhost:5432 for a psql client +sprite proxy 5432 ``` -### Development Server +The distinction in one line: -Let's say you've got a frontend or backend dev server that watches files and hot reloads. +| | Sprite URL | `sprite proxy` | +|---|---|---| +| Protocol | HTTP(S) only | Any TCP | +| Reach | Public Internet | Your machine only | +| Needs the CLI running | No | Yes | +| Ports | One (the HTTP service) | As many as you forward | -```bash -# Start dev server in detachable session -sprite exec -detachable "cd /home/sprite/app && npm run dev" +`sprite proxy` also remaps ports (`sprite proxy 3001:3000`) and tunnels stdin and stdout for things like SSH (`sprite proxy -W :22`). And you often don't reach for it at all: when you run `sprite exec` and your command opens a listening port, the CLI forwards that port to your laptop automatically. For the full command surface and the SSH-over-proxy setup, see [Working with Sprites](/working-with-sprites#networking-urls-and-port-forwarding) and the [CLI Commands reference](/cli/commands#networking). -# Forward the port locally -sprite proxy 3000 +The HTTP service the URL routes to, including how it wakes on an incoming request and how to move it off the default port, is [Services](/concepts/services). -# Open in browser -open http://localhost:3000 -``` -If your server starts dynamically (e.g. via a watcher), Sprites can emit events when a process binds a port. You can hook into those if you want to script around startup behavior. +## URL authentication -### Database Access +A Sprite URL is private by default. It's reachable only by members of your org, through the browser or with an org token, so standing up a service doesn't put it on the open Internet by accident. -Running a database inside a Sprite is weirdly nice. You can spin up Postgres, forward its port, and connect with your usual tools: +Make it public when you actually want that, a webhook that needs to be hit without a token, a demo you're sharing, something quick on the Internet: ```bash -# Start PostgreSQL (if installed) -sprite exec -detachable "pg_ctl start" - -# Forward port locally -sprite proxy 5432 +# Anyone with the URL can reach it +sprite url update --auth public -# Connect with local tools -psql -h localhost -p 5432 -U postgres +# Back to org-only (the default) +sprite url update --auth sprite ``` -### Multiple Services + +Public means no authentication: anyone with the URL reaches whatever the HTTP service serves. Don't make a URL public while it exposes secrets, tokens, or internal endpoints, and put your own auth in front of anything real. Flip it back to `sprite` when you're done. + -Sprites can run multiple processes. You can forward all the ports you care about: +## Reaching out -```bash -# Start multiple services -sprite exec -detachable "cd /home/sprite/api && npm start" # Port 3000 -sprite exec -detachable "cd /home/sprite/worker && npm start" # Port 3001 -sprite exec -detachable "redis-server" # Port 6379 +Outbound traffic is not wide open. A Sprite's egress is governed by a **network policy**: a DNS-based allow-list that decides which domains the Sprite can resolve and reach. A request to an allowed domain works normally. A request to one that isn't gets a DNS `REFUSED` and fails fast, rather than hanging. + +The policy is a set of rules, read-only inside the Sprite at `/.sprite/policy/network.json`: -# Forward all ports -sprite proxy 3000 3001 6379 +```json +{ + "rules": [ + { "include": "defaults" }, + { "domain": "example.com", "action": "allow" }, + { "domain": "*.example.com", "action": "allow" }, + { "domain": "blocked.com", "action": "deny" } + ] +} ``` -## Network Behavior +- **`{ "include": "defaults" }`** pulls in the common development domains, GitHub, npm, PyPI, Docker Hub, and the major AI APIs among them, so package installs and model calls work without listing every host yourself. +- **Domain rules** match an exact host (`example.com`), a subdomain wildcard (`*.example.com`), or everything (`*`). More specific rules win: an exact match beats a subdomain wildcard, which beats the global wildcard. +- **`{ "rules": [] }`** means no enforcement. The Sprite runs unrestricted. -Sprites have full network access by default: +A few behaviors follow from the DNS-based design: -- **Outbound**: All protocols and ports. You can fetch packages, call APIs and more -- **Inbound**: Only via Sprite URL or port forwarding -- **DNS**: Standard resolution works +- **Raw IP connections are blocked** unless the IP was resolved from an allowed domain. You can't route around the allow-list by dialing an address directly. +- **Private IPs are always blocked**, so a Sprite can't reach into private network ranges. +- **Changes reload live.** When a policy tightens, existing connections to newly-blocked domains are dropped rather than left open. -The default environment includes common network tools, and you can install additional ones as needed. You can run tools like `netcat`, `curl`, or `nmap` or `wget`. Nothing is artificially restricted and this isn't a locked-down environment. +The policy is read-only from inside: a Sprite can't rewrite its own egress rules. Changes are made from outside through the [Sprites API](https://sprites.dev/api). To test what the current policy allows, resolve a domain and watch for `REFUSED`: -Example network tool installation: ```bash -sprite exec "apt-get update && apt-get install -y nmap netcat" +dig github.com # an allowed domain resolves +dig blocked.com # a denied domain returns REFUSED ``` -## Troubleshooting - -**Not seeing your app on the URL?** Make sure it's listening on `0.0.0.0`, not `localhost`. The router can't see loopback-only services. - -**Forwarded port not responding?** Check the app is actually running, and that you forwarded the right port. Use `sprite ps` to see running processes. - -**Getting a 403 on your Sprite URL?** It's probably set to private. Make it public with `sprite url --public` or authenticate with a token. - -**Dynamic apps not ready right away?** If your service binds ports after startup, you can use port open events from the SDK to wait for readiness. - -## Security Notes +For calling external APIs without handing the Sprite a long-lived credential, [Connectors](/concepts/connectors) route the request through a gateway that holds the token for you. That's a separate mechanism from the egress policy: the policy decides what a Sprite may reach, Connectors decide what it may reach *as*. -By default, your Sprite isn't publicly accessible. That's on purpose. You control what gets exposed — either by forwarding a port or making the Sprite's URL public. - -A few things to keep in mind: - -- **Only expose what you actually need** - Run services on specific ports -- **Use app-level auth** - If you're building anything real, implement your own authentication -- **Forwarded ports are reachable from your machine** — Not the wider Internet. -- **Temporary exposure** - Make public only when needed. - -We don't add firewall rules or block inbound traffic to forwarded ports, but we also don't auto-protect what you expose. You're in control, which is powerful — and dangerous, if you're not paying attention. Keep it minimal and secure. - -## Related Documentation +## Related documentation diff --git a/src/lib/sidebar.ts b/src/lib/sidebar.ts index b4aeeda..89e5f2c 100644 --- a/src/lib/sidebar.ts +++ b/src/lib/sidebar.ts @@ -141,6 +141,7 @@ export const sidebarConfig: SidebarGroup[] = [ { label: 'Checkpoints', slug: 'concepts/checkpoints' }, { label: 'Connectors', slug: 'concepts/connectors' }, { label: 'Lifecycle and Persistence', slug: 'concepts/lifecycle' }, + { label: 'Networking', slug: 'concepts/networking' }, { label: 'Services', slug: 'concepts/services' }, ], }, From f48f8bc1163cd79d6fd2f5ee02509b347ea513ea Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 17:38:16 +0000 Subject: [PATCH 02/15] Clarify Networking intro: frame by direction, not count --- src/content/docs/concepts/networking.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 9cf4f8d..fb92ba9 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -7,7 +7,7 @@ author: kcmartin import { Callout, LinkCard, CardGrid } from '@/components/react'; -A Sprite runs your code in the cloud, but it's meant to feel close. There are two ways traffic gets in, an always-on HTTPS URL and a proxy that maps a remote port onto your laptop, and one policy that governs what the Sprite can reach on its way out. This page is the model for all three. The exact commands live on the pages linked throughout. +A Sprite runs your code in the cloud, but it's meant to feel close. Traffic gets in two ways, an always-on HTTPS URL and a proxy that maps a remote port onto your laptop, while a single policy governs what the Sprite can reach on its way out. This page is the model for both directions: how you reach in, and what a Sprite can reach going out. The exact commands live on the pages linked throughout. ## Reaching a Sprite From 0b87dcdfc232d205e031c7f103c4eec55140a057 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 17:41:00 +0000 Subject: [PATCH 03/15] Reword Services cross-reference in Networking --- src/content/docs/concepts/networking.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index fb92ba9..9551b9e 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -35,7 +35,7 @@ The distinction in one line: `sprite proxy` also remaps ports (`sprite proxy 3001:3000`) and tunnels stdin and stdout for things like SSH (`sprite proxy -W :22`). And you often don't reach for it at all: when you run `sprite exec` and your command opens a listening port, the CLI forwards that port to your laptop automatically. For the full command surface and the SSH-over-proxy setup, see [Working with Sprites](/working-with-sprites#networking-urls-and-port-forwarding) and the [CLI Commands reference](/cli/commands#networking). -The HTTP service the URL routes to, including how it wakes on an incoming request and how to move it off the default port, is [Services](/concepts/services). +The HTTP service the URL routes to, including how it wakes on an incoming request and how to move it off the default port, is covered in [Services](/concepts/services). ## URL authentication From c5b1492259cc3f4580770996c9cb185d09ea4c3b Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 17:43:46 +0000 Subject: [PATCH 04/15] Reword public URL use cases in Networking --- src/content/docs/concepts/networking.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 9551b9e..5dacaad 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -41,7 +41,7 @@ The HTTP service the URL routes to, including how it wakes on an incoming reques A Sprite URL is private by default. It's reachable only by members of your org, through the browser or with an org token, so standing up a service doesn't put it on the open Internet by accident. -Make it public when you actually want that, a webhook that needs to be hit without a token, a demo you're sharing, something quick on the Internet: +Make it public when you actually want that behavior, for example, a webhook that needs to be hit without a token, a demo you're sharing, or putting something quick on the Internet: ```bash # Anyone with the URL can reach it From fe9a66fe492be22300fb08e65ba4ed9a54de075b Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 17:45:14 +0000 Subject: [PATCH 05/15] Use 'if' in public URL warning --- src/content/docs/concepts/networking.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 5dacaad..9054993 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -52,7 +52,7 @@ sprite url update --auth sprite ``` -Public means no authentication: anyone with the URL reaches whatever the HTTP service serves. Don't make a URL public while it exposes secrets, tokens, or internal endpoints, and put your own auth in front of anything real. Flip it back to `sprite` when you're done. +Public means no authentication: anyone with the URL reaches whatever the HTTP service serves. Don't make a URL public if it exposes secrets, tokens, or internal endpoints, and put your own auth in front of anything real. Flip it back to `sprite` when you're done. ## Reaching out From b941b3cbb78f9a2179cb129ed8662bd243e826f0 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 17:46:56 +0000 Subject: [PATCH 06/15] Use 'allowlist' spelling in Networking --- src/content/docs/concepts/networking.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 9054993..c8d7a8f 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -57,7 +57,7 @@ Public means no authentication: anyone with the URL reaches whatever the HTTP se ## Reaching out -Outbound traffic is not wide open. A Sprite's egress is governed by a **network policy**: a DNS-based allow-list that decides which domains the Sprite can resolve and reach. A request to an allowed domain works normally. A request to one that isn't gets a DNS `REFUSED` and fails fast, rather than hanging. +Outbound traffic is not wide open. A Sprite's egress is governed by a **network policy**: a DNS-based allowlist that decides which domains the Sprite can resolve and reach. A request to an allowed domain works normally. A request to one that isn't gets a DNS `REFUSED` and fails fast, rather than hanging. The policy is a set of rules, read-only inside the Sprite at `/.sprite/policy/network.json`: @@ -78,7 +78,7 @@ The policy is a set of rules, read-only inside the Sprite at `/.sprite/policy/ne A few behaviors follow from the DNS-based design: -- **Raw IP connections are blocked** unless the IP was resolved from an allowed domain. You can't route around the allow-list by dialing an address directly. +- **Raw IP connections are blocked** unless the IP was resolved from an allowed domain. You can't route around the allowlist by dialing an address directly. - **Private IPs are always blocked**, so a Sprite can't reach into private network ranges. - **Changes reload live.** When a policy tightens, existing connections to newly-blocked domains are dropped rather than left open. From 997ec99e502c1fe417a53cdfffd152a9101d9b90 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 17:50:22 +0000 Subject: [PATCH 07/15] Add closing bookend to Networking page --- src/content/docs/concepts/networking.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index c8d7a8f..35be7d4 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -91,6 +91,8 @@ dig blocked.com # a denied domain returns REFUSED For calling external APIs without handing the Sprite a long-lived credential, [Connectors](/concepts/connectors) route the request through a gateway that holds the token for you. That's a separate mechanism from the egress policy: the policy decides what a Sprite may reach, Connectors decide what it may reach *as*. +That's the shape of it: the URL and proxy control how you reach a Sprite, the egress policy controls how far it reaches back. Keep both no wider than the work needs. + ## Related documentation From 880d3d73dc401931728b96eba6e6eee9451e3466 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 17:54:05 +0000 Subject: [PATCH 08/15] Warm up Networking closing line --- src/content/docs/concepts/networking.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 35be7d4..00143f2 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -91,7 +91,7 @@ dig blocked.com # a denied domain returns REFUSED For calling external APIs without handing the Sprite a long-lived credential, [Connectors](/concepts/connectors) route the request through a gateway that holds the token for you. That's a separate mechanism from the egress policy: the policy decides what a Sprite may reach, Connectors decide what it may reach *as*. -That's the shape of it: the URL and proxy control how you reach a Sprite, the egress policy controls how far it reaches back. Keep both no wider than the work needs. +That's the shape of networking on Sprites: the URL and proxy control how you reach a Sprite, the egress policy controls how far it reaches back. You're in control of both, so it's worth opening each only as far as your work actually needs. ## Related documentation From 86e5904905dec9e813ca30a297a408336473528d Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 18:00:53 +0000 Subject: [PATCH 09/15] Add allowlist to Vale accept vocabulary --- styles/config/vocabularies/fly-terms/accept.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/styles/config/vocabularies/fly-terms/accept.txt b/styles/config/vocabularies/fly-terms/accept.txt index 9063181..adcd5f5 100644 --- a/styles/config/vocabularies/fly-terms/accept.txt +++ b/styles/config/vocabularies/fly-terms/accept.txt @@ -1,4 +1,5 @@ alignItems +allowlist Alertmanager Ansible Anthropic's From c72b1aa10c26e00ca006d6b547c2ecdd5fd72382 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 18:13:52 +0000 Subject: [PATCH 10/15] Clarify egress is unrestricted by default, policy is opt-in --- src/content/docs/concepts/networking.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 00143f2..5fdb31e 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -57,7 +57,7 @@ Public means no authentication: anyone with the URL reaches whatever the HTTP se ## Reaching out -Outbound traffic is not wide open. A Sprite's egress is governed by a **network policy**: a DNS-based allowlist that decides which domains the Sprite can resolve and reach. A request to an allowed domain works normally. A request to one that isn't gets a DNS `REFUSED` and fails fast, rather than hanging. +By default, a Sprite's outbound is unrestricted: it can resolve and reach any domain. Egress can be tightened with a **network policy**, a DNS-based allowlist that decides which domains a Sprite is allowed to reach. Applying one is opt-in and done from outside the Sprite. Once a policy is in force, a request to an allowed domain works normally, while a request to one that isn't gets a DNS `REFUSED` and fails fast rather than hanging. The policy is a set of rules, read-only inside the Sprite at `/.sprite/policy/network.json`: @@ -76,7 +76,7 @@ The policy is a set of rules, read-only inside the Sprite at `/.sprite/policy/ne - **Domain rules** match an exact host (`example.com`), a subdomain wildcard (`*.example.com`), or everything (`*`). More specific rules win: an exact match beats a subdomain wildcard, which beats the global wildcard. - **`{ "rules": [] }`** means no enforcement. The Sprite runs unrestricted. -A few behaviors follow from the DNS-based design: +When a policy is enforced, a few behaviors follow from its DNS-based design: - **Raw IP connections are blocked** unless the IP was resolved from an allowed domain. You can't route around the allowlist by dialing an address directly. - **Private IPs are always blocked**, so a Sprite can't reach into private network ranges. From 8d9f746e2e9f7bbe9f8cc0d4a0003d6eb337e311 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 19:11:17 +0000 Subject: [PATCH 11/15] Address review feedback: split intro sentence, replace deprecated sprite url --- src/content/docs/concepts/networking.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 5fdb31e..2165ba6 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -7,7 +7,7 @@ author: kcmartin import { Callout, LinkCard, CardGrid } from '@/components/react'; -A Sprite runs your code in the cloud, but it's meant to feel close. Traffic gets in two ways, an always-on HTTPS URL and a proxy that maps a remote port onto your laptop, while a single policy governs what the Sprite can reach on its way out. This page is the model for both directions: how you reach in, and what a Sprite can reach going out. The exact commands live on the pages linked throughout. +A Sprite runs your code in the cloud, but it's meant to feel close. Traffic gets in two ways, an always-on HTTPS URL and a proxy that maps a remote port onto your laptop. A network policy governs what the Sprite can reach on its way out. This page is the model for both directions: how you reach in, and what a Sprite can reach going out. The exact commands live on the pages linked throughout. ## Reaching a Sprite @@ -17,8 +17,8 @@ Inbound traffic arrives one of two ways, and which you pick depends on whether y - **`sprite proxy`** maps a remote port onto your machine so the Sprite feels local. It forwards any TCP protocol, not just HTTP, which is how you point a database client or a browser at a service running in the Sprite. It's local to your machine, not the Internet, and it only runs while the CLI does. ```bash -# Always-on HTTPS to the Sprite's HTTP service -sprite url +# Show the Sprite's URL and its auth setting +sprite info # Map the Sprite's port 5432 onto localhost:5432 for a psql client sprite proxy 5432 @@ -120,7 +120,7 @@ That's the shape of networking on Sprites: the URL and proxy control how you rea From 61b73876dc963fcfc916fb2612b8a70f08df2f37 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 19:23:35 +0000 Subject: [PATCH 12/15] Rework URL vs proxy bullets so the table carries the comparison --- src/content/docs/concepts/networking.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 2165ba6..326a145 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -13,8 +13,8 @@ A Sprite runs your code in the cloud, but it's meant to feel close. Traffic gets Inbound traffic arrives one of two ways, and which you pick depends on whether you want a public endpoint or a local one. -- **The Sprite URL** is always on and needs no CLI. Every Sprite has one at `https://-.sprites.dev/`, and it routes HTTPS to the Sprite's HTTP service. It's the way to reach an app over the Internet: a webhook target, a shared demo, an API. It carries HTTP(S) to a single port. -- **`sprite proxy`** maps a remote port onto your machine so the Sprite feels local. It forwards any TCP protocol, not just HTTP, which is how you point a database client or a browser at a service running in the Sprite. It's local to your machine, not the Internet, and it only runs while the CLI does. +- **The Sprite URL** is how you reach an app over the Internet: a webhook target, a shared demo, an API. Every Sprite has one at `https://-.sprites.dev/`, and it routes HTTPS to the Sprite's HTTP service. It's always on: no CLI required. +- **`sprite proxy`** is how you make a Sprite feel local: it maps a remote port onto your machine, so you can point a database client or a browser at a service running in the Sprite. ```bash # Show the Sprite's URL and its auth setting @@ -24,8 +24,6 @@ sprite info sprite proxy 5432 ``` -The distinction in one line: - | | Sprite URL | `sprite proxy` | |---|---|---| | Protocol | HTTP(S) only | Any TCP | From 8f14cee92e3a68e50aef16dbb48ca169effc20aa Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 19:39:44 +0000 Subject: [PATCH 13/15] Use sprites.app for the Sprite URL domain, matching #186 --- src/content/docs/concepts/networking.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 326a145..ca30ff2 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -13,7 +13,7 @@ A Sprite runs your code in the cloud, but it's meant to feel close. Traffic gets Inbound traffic arrives one of two ways, and which you pick depends on whether you want a public endpoint or a local one. -- **The Sprite URL** is how you reach an app over the Internet: a webhook target, a shared demo, an API. Every Sprite has one at `https://-.sprites.dev/`, and it routes HTTPS to the Sprite's HTTP service. It's always on: no CLI required. +- **The Sprite URL** is how you reach an app over the Internet: a webhook target, a shared demo, an API. Every Sprite has one at `https://-.sprites.app/`, and it routes HTTPS to the Sprite's HTTP service. It's always on: no CLI required. - **`sprite proxy`** is how you make a Sprite feel local: it maps a remote port onto your machine, so you can point a database client or a browser at a service running in the Sprite. ```bash From d3ef7038072d5ba441a668b5f47ce3deceb40c66 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 19:42:49 +0000 Subject: [PATCH 14/15] Use sprite config update --url-auth for changing URL auth --- src/content/docs/concepts/networking.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index ca30ff2..47972c1 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -43,10 +43,10 @@ Make it public when you actually want that behavior, for example, a webhook that ```bash # Anyone with the URL can reach it -sprite url update --auth public +sprite config update --url-auth public # Back to org-only (the default) -sprite url update --auth sprite +sprite config update --url-auth sprite ``` From 3a109e7775616e81d35dbadbb41131d0e09c1655 Mon Sep 17 00:00:00 2001 From: Kristin Martin Date: Wed, 8 Jul 2026 19:51:10 +0000 Subject: [PATCH 15/15] Clarify that the URL suffix is an org ID, not the org name --- src/content/docs/concepts/networking.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/concepts/networking.mdx b/src/content/docs/concepts/networking.mdx index 47972c1..882b2f1 100644 --- a/src/content/docs/concepts/networking.mdx +++ b/src/content/docs/concepts/networking.mdx @@ -13,7 +13,7 @@ A Sprite runs your code in the cloud, but it's meant to feel close. Traffic gets Inbound traffic arrives one of two ways, and which you pick depends on whether you want a public endpoint or a local one. -- **The Sprite URL** is how you reach an app over the Internet: a webhook target, a shared demo, an API. Every Sprite has one at `https://-.sprites.app/`, and it routes HTTPS to the Sprite's HTTP service. It's always on: no CLI required. +- **The Sprite URL** is how you reach an app over the Internet: a webhook target, a shared demo, an API. Every Sprite has one at `https://-.sprites.app/` (the org ID is a short generated identifier; `sprite info` prints your exact URL), and it routes HTTPS to the Sprite's HTTP service. It's always on: no CLI required. - **`sprite proxy`** is how you make a Sprite feel local: it maps a remote port onto your machine, so you can point a database client or a browser at a service running in the Sprite. ```bash