Skip to main content
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. 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/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. 
curl -X POST https://api.rigbox.dev/api/apps \
  -H "Authorization: Bearer $RIGBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "'$WORKSPACE_ID'",
    "name": "my-api",
    "port": 8080
  }'
See Create App for the full request/response schema.

​
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/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/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/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. 
curl -X POST https://api.rigbox.dev/api/apps/$APP_ID/stop \
  -H "Authorization: Bearer $RIGBOX_API_KEY"
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 details.

​
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/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. 
curl -X DELETE https://api.rigbox.dev/api/apps/$APP_ID \
  -H "Authorization: Bearer $RIGBOX_API_KEY"
See Delete App for details.

​
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 your local machine, expose port 8080: 
import requests

API_URL = "https://api.rigbox.dev/api"
HEADERS = {"Authorization": f"Bearer {api_key}"}

# Expose port 8080
app = requests.post(
    f"{API_URL}/workspaces/{workspace_id}/expose-port",
    headers=HEADERS,
    json={"port": 8080},
).json()

app_id = app["id"]
app_url = f"https://{app['name']}.rigbox.dev"
print(f"App created: {app_url}")

​
Verify health

import time

# Wait a moment for the route to propagate
time.sleep(3)

health = requests.get(
    f"{API_URL}/apps/{app_id}/health",
    headers=HEADERS,
).json()

if health["healthy"]:
    print(f"App is live at {app_url}")
else:
    print("App is not healthy yet — check the service is running")

​
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