How to run a web service in a sandbox?

Start a web server in a sandbox, forward a host port to it, and call it from the host:

CLI

shard create --name web --memory 512MiB python:3.12
shard exec web sh -c 'mkdir -p /srv && echo "hello from shard" > /srv/index.html'
shard run web --name site -- python3 -m http.server 8000 --directory /srv
shard port add web 9000:8000
curl -sS http://127.0.0.1:9000/

TypeScript

import { Shard } from "useshards";

const shard = new Shard();
try {
  const web = await shard.create({ name: "web", image: "python:3.12", memoryMiB: 512 });
  await web.exec(["sh", "-c", 'mkdir -p /srv && echo "hello from shard" > /srv/index.html']);
  await web.run(["python3", "-m", "http.server", "8000", "--directory", "/srv"], { name: "site" });
  const forward = await web.ports.add(9000, 8000);
  console.log(forward.listening, forward.reachableOn);
} finally {
  shard.close();
}

Python

from useshards import Shard

with Shard() as shard:
    web = shard.create("python:3.12", name="web", memory_mib=512)
    web.exec(["sh", "-c", 'mkdir -p /srv && echo "hello from shard" > /srv/index.html'])
    web.run(["python3", "-m", "http.server", "8000", "--directory", "/srv"], name="site")
    forward = web.ports.add(9000, 8000)
    print(forward.listening, forward.reachable_on)

The TypeScript and Python examples reach shard serve at the address in SHARD_REMOTE, with the API key in SHARD_API_KEY. Their forward listens on that server, not on your machine.

curl prints hello from shard. The server keeps running after the command returns, and the sandbox stays running until you stop it.

Why run and not exec

shard exec runs a command and waits for it. shard run starts a named process that shard-init supervises in the background, so it suits a server:

	shard exec	shard run
Waits for the command	yes	no, it prints the process name and returns
Has a name	no	yes, site here
Restarts after an exit	no	by its restart policy
Keeps its output	no, it streams it	yes, shard logs reads it

A sandbox runs up to 16 processes, each under its own name.

Restarts

Without --restart, the policy is unless-stopped. shard starts the process again after any exit, and again when the sandbox starts, until shard kill ends it.

To restart only after a nonzero exit, and give up after five tries:

shard run web --name site --restart on-failure --restart-retries 5 -- python3 -m http.server 8000 --directory /srv

--restart-retries applies to on-failure only. A run of a name that has ended replaces it, so this works after shard kill web site.

The delay before a restart starts at 1s and doubles after each restart, up to 60s. --restart-backoff sets the first delay.

Watch the process

shard ps web
shard logs web site
shard logs web site -f

shard ps shows each process with its state, its restarts and its last exit code. shard logs prints the output of every run of the process, restarts included. -f keeps printing new output until the process ends or the sandbox stops.

To stop the server and cancel its restarts, while the sandbox keeps running:

shard kill web site

A process started with --restart always still comes back when the sandbox starts again.

Forward a port

shard port add web 9000:8000 forwards host port 9000 to port 8000 in the sandbox. shard port add web 8000 uses the same port on both sides.

The host listens on 127.0.0.1 only, so nothing beyond the host reaches the port. Each connection goes to the sandbox’s own 127.0.0.1, so the server must listen there or on every interface.

shard create --port 9000:8000 forwards the port from the first start, so the create and the forward are one command:

shard create --name web --memory 512MiB --port 9000:8000 python:3.12

A forward belongs to the sandbox. It survives a stop, a start, a daemon restart and a reboot of the host. The host listens only while the sandbox runs. A fork does not copy the forwards.

shard port list
shard port remove web 9000

Open it to other machines

--public makes the host listen on 0.0.0.0, and the command prints each address of the host that the port is now reachable on:

shard port add web 9000:8000 --public

lo     127.0.0.1:9000
eth0   192.0.2.20:9000

Warning

A public port is open to every network the host is on. Anyone who reaches the host can connect to the server in the sandbox, and shard checks nothing on the way. Put a proxy that terminates TLS and checks who calls in front of it, or keep the port on 127.0.0.1.

Add the same host port again without --public to close it to other machines.

Clean up

shard remove --force web

The remove ends the server, the sandbox and its forwards.