Networking

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.

Sprite URLs

Every Sprite has a unique URL for HTTPS access, for example:

sprite url

https://my-sprite-abc123.sprites.dev

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:

CLI

# 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).

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:

CLI

# 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()
    }
}()

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:

# Start a simple HTTP server
sprite exec -detachable "python -m http.server 8080"

# Get the URL
sprite url

https://my-sprite-abc123.sprites.dev

# Access via browser or curl (after making public)
curl https://my-sprite-abc123.sprites.dev:8080/

Development Server

Let’s say you’ve got a frontend or backend dev server that watches files and hot reloads.

# Start dev server in detachable session
sprite exec -detachable "cd /home/sprite/app && npm run dev"

# Forward the port locally
sprite proxy 3000

# 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.

Database Access

Running a database inside a Sprite is weirdly nice. You can spin up Postgres, forward its port, and connect with your usual tools:

# Start PostgreSQL (if installed)
sprite exec -detachable "pg_ctl start"

# Forward port locally
sprite proxy 5432

# Connect with local tools
psql -h localhost -p 5432 -U postgres

Multiple Services

Sprites can run multiple processes. You can forward all the ports you care about:

# 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

# Forward all ports
sprite proxy 3000 3001 6379

Network Behavior

Sprites have full network access by default:

• 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

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.

Example network tool installation:

sprite exec "apt-get update && apt-get install -y nmap netcat"

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

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

Working with Sprites

Beyond the basics guide to using Sprites

CLI Commands

Complete command reference

Configuration

Network settings and options

Lifecycle

Hibernation and persistence behavior