Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rigbox.dev/llms.txt

Use this file to discover all available pages before exploring further.

When a service runs inside your workspace, it’s only accessible within the VM by default. To make it reachable from the internet, you create an app - a route that maps an internal port to a public URL at {name}.rigbox.dev.

​
How Routing Works

The flow from a running service to a public URL: Each app gets a unique subdomain on rigbox.dev of the form <APP_NAME>.rigbox.dev, where <APP_NAME> is the name you choose when creating the app. HTTPS is handled automatically - your service only needs to listen on HTTP inside the VM.
App subdomains are globally unique across all Rigbox users. If a name is taken, you’ll need to choose a different one.

​
Discover Listening Ports

Before exposing a port, you can check which ports have active listeners inside the workspace. 
curl -s https://api.rigbox.dev/api/v1/workspaces/$WORKSPACE_ID/listening-ports \
  -H "Authorization: Bearer $RIGBOX_API_KEY" | jq
This scans the workspace for active TCP listeners and returns the port number along with the process name when available. See List Listening Ports for the full response schema.

​
Create an App Manually

If you know the port and want full control over the app name, create it directly. Replace <APP_NAME> with a name of your choice — it will become the public subdomain. 
rig app new --name <APP_NAME> --port 8080
From outside the workspace, add --workspace <WORKSPACE_NAME> to target a specific VM. Pass --kind cli for interactive tools you’ll invoke over SSH rather than expose as a public service. See Create App for the API form.

​
Expose Port Shortcut

The expose-port endpoint detects the process listening on the specified port and creates an app in one call. This is the easiest way to make a service public. 
curl -X POST https://api.rigbox.dev/api/v1/workspaces/$WORKSPACE_ID/expose-port \
  -H "Authorization: Bearer $RIGBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "port": 3000
  }'
The endpoint automatically detects the process name and uses it to generate a sensible app name. See Expose Port for details.

​
Reconcile Template Apps

If your workspace was created from a template that defines default apps (like a web server or API), you can ensure those apps exist with a reconcile call. 
curl -X POST https://api.rigbox.dev/api/v1/workspaces/$WORKSPACE_ID/reconcile-apps \
  -H "Authorization: Bearer $RIGBOX_API_KEY"
This checks the template definition and creates any missing apps. It’s idempotent - running it multiple times has no side effects. See Reconcile Apps for details.

​
Check App Health

Before sharing a URL, verify the app is reachable. 
curl -s https://api.rigbox.dev/api/v1/apps/$APP_ID/health \
  -H "Authorization: Bearer $RIGBOX_API_KEY" | jq
If health returns unhealthy, check that your service is actually listening on the correct port inside the VM. Use the listening-ports endpoint to verify.
See App Health for the response schema.

​
App Lifecycle: Start, Stop, Restart

Control the routing for an app without affecting the underlying service: 
rig app stop <APP_NAME>
rig app start <APP_NAME>
rig app restart <APP_NAME>
ActionEffect
stopRemoves the public route. The service inside the VM keeps running.
startRe-enables the public route.
restartRemoves and re-adds the route. Useful if the proxy is in a bad state.
See Start App, Stop App, and Restart App for the API form.

​
Update an App

You can rename an app or change its port. Renaming an app changes its public subdomain URL. 
curl -X PATCH https://api.rigbox.dev/api/v1/apps/$APP_ID \
  -H "Authorization: Bearer $RIGBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-name"
  }'
Renaming an app changes its public URL. Any existing links to the old subdomain will stop working immediately.
See Update App for the full schema.

​
Delete an App

Deleting an app removes the public route. The service inside the VM is unaffected. 
rig app rm <APP_NAME>
See Delete App for the API form.

​
Complete Example: Deploy a Python Server

This walkthrough starts a Python HTTP server inside a workspace and exposes it to the internet.

​
Start a service inside the VM

SSH into your workspace and start a simple Python server: 
# Inside the VM
python3 -m http.server 8080 &

​
Expose the port

From inside the same workspace (or from your laptop with --workspace <NAME>): 
rig app new --name my-server --port 8080
rig app new prints the resulting subdomain — https://my-server.rigbox.dev. If you’d rather have Rigbox detect the listening process and pick a name automatically, the Expose Port API endpoint does both in one shot.

​
Verify health

curl -sf https://my-server.rigbox.dev/ -o /dev/null && echo "live" || echo "not ready yet"
For programmatic health checks via Rigbox’s own probe, see App Health.

​
Share the URL

Once healthy, anyone with the URL can access your service (if visibility is set to public). See App Visibility to control access.

​
Next Steps

  • App Visibility - control who can access your apps
  • Catalog Apps - install VS Code, Jupyter, and more (routing is handled automatically)
  • Workspaces - workspace lifecycle management