App Server

portr app-server

http://127.0.0.1:7778

portr app-server --host 127.0.0.1 --port 7780

portr --config ~/.portr/config.yaml app-server

PORTR_APP_SERVER_TOKEN="change-me" portr app-server

portr app-server --token "change-me"

Authorization: Bearer change-me

curl -H "Authorization: Bearer change-me" \
  http://127.0.0.1:7778/api/v1/tunnels

{
  "message": "port must be between 1 and 65535"
}

curl -X POST http://127.0.0.1:7778/api/v1/tunnels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "type": "http",
    "host": "localhost",
    "port": 3000
  }'

curl -X POST http://127.0.0.1:7778/api/v1/tunnels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "type": "http",
    "host": "localhost",
    "port": 3000,
    "subdomain": "my-app"
  }'

{
  "id": "01HZYR9VK2C0G6KTX4TK9Z5T6S",
  "name": "web",
  "status": "running",
  "type": "http",
  "host": "localhost",
  "port": 3000,
  "subdomain": "my-app",
  "tunnel_url": "https://my-app.example.com",
  "callback_urls": [],
  "started_at": "2026-05-15T10:00:00Z",
  "updated_at": "2026-05-15T10:00:05Z"
}

curl -X POST http://127.0.0.1:7778/api/v1/tunnels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "postgres",
    "type": "tcp",
    "host": "localhost",
    "port": 5432
  }'

{
  "id": "01HZYRA72P4R8PQVG0YSQXJK64",
  "name": "postgres",
  "status": "running",
  "type": "tcp",
  "host": "localhost",
  "port": 5432,
  "remote_port": 49160,
  "tunnel_url": "example.com:49160",
  "started_at": "2026-05-15T10:05:00Z",
  "updated_at": "2026-05-15T10:05:04Z"
}

curl http://127.0.0.1:7778/api/v1/tunnels

{
  "tunnels": [
    {
      "id": "01HZYR9VK2C0G6KTX4TK9Z5T6S",
      "name": "web",
      "status": "running",
      "type": "http",
      "host": "localhost",
      "port": 3000,
      "subdomain": "my-app",
      "tunnel_url": "https://my-app.example.com",
      "started_at": "2026-05-15T10:00:00Z",
      "updated_at": "2026-05-15T10:00:05Z"
    }
  ]
}

curl http://127.0.0.1:7778/api/v1/tunnels/01HZYR9VK2C0G6KTX4TK9Z5T6S

curl -X DELETE \
  http://127.0.0.1:7778/api/v1/tunnels/01HZYR9VK2C0G6KTX4TK9Z5T6S

curl -X POST \
  http://127.0.0.1:7778/api/v1/tunnels/01HZYR9VK2C0G6KTX4TK9Z5T6S/shutdown

curl http://127.0.0.1:7778/api/v1/events

curl "http://127.0.0.1:7778/api/v1/events?tunnel_id=01HZYR9VK2C0G6KTX4TK9Z5T6S"

{
  "events": [
    {
      "id": "01HZYRBYT1DD8W7GK8RJ0QYTS4",
      "tunnel_id": "01HZYR9VK2C0G6KTX4TK9Z5T6S",
      "type": "started",
      "name": "web",
      "connection_type": "http",
      "host": "localhost",
      "port": 3000,
      "subdomain": "my-app",
      "tunnel_url": "https://my-app.example.com",
      "at": "2026-05-15T10:00:05Z"
    }
  ]
}

curl -X POST http://127.0.0.1:7778/api/v1/tunnels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "type": "http",
    "host": "localhost",
    "port": 3000,
    "subdomain": "my-app",
    "callback_url": "http://127.0.0.1:9000/portr-events",
    "callback_urls": [
      "https://automation.example.com/webhooks/portr"
    ]
  }'

{
  "id": "01HZYRBYT1DD8W7GK8RJ0QYTS4",
  "tunnel_id": "01HZYR9VK2C0G6KTX4TK9Z5T6S",
  "type": "reconnected",
  "name": "web",
  "connection_type": "http",
  "host": "localhost",
  "port": 3000,
  "subdomain": "my-app",
  "tunnel_url": "https://my-app.example.com",
  "at": "2026-05-15T10:10:00Z"
}

APP_SERVER=http://127.0.0.1:7778

TUNNEL_ID=$(
  curl -sS -X POST "$APP_SERVER/api/v1/tunnels" \
    -H "Content-Type: application/json" \
    -d '{"name":"preview","type":"http","host":"localhost","port":3000}' |
    jq -r '.id'
)

curl -sS "$APP_SERVER/api/v1/tunnels/$TUNNEL_ID"

# Run your automated workflow here.

curl -sS -X DELETE "$APP_SERVER/api/v1/tunnels/$TUNNEL_ID"

import json
import os
import urllib.request

APP_SERVER = os.getenv("PORTR_APP_SERVER", "http://127.0.0.1:7778")
TOKEN = os.getenv("PORTR_APP_SERVER_TOKEN")


def api(method, path, payload=None):
    data = json.dumps(payload).encode("utf-8") if payload else None
    headers = {"Content-Type": "application/json"}
    if TOKEN:
        headers["Authorization"] = f"Bearer {TOKEN}"

    request = urllib.request.Request(
        f"{APP_SERVER}{path}",
        data=data,
        headers=headers,
        method=method,
    )

    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode("utf-8"))


tunnel = api(
    "POST",
    "/api/v1/tunnels",
    {
        "name": "python-preview",
        "type": "http",
        "host": "localhost",
        "port": 3000,
    },
)

print("Tunnel URL:", tunnel.get("tunnel_url"))
input("Press Enter to stop the tunnel...")

api("DELETE", f"/api/v1/tunnels/{tunnel['id']}")

const APP_SERVER = process.env.PORTR_APP_SERVER ?? "http://127.0.0.1:7778";
const TOKEN = process.env.PORTR_APP_SERVER_TOKEN;

async function api(method, path, payload) {
  const headers = { "Content-Type": "application/json" };
  if (TOKEN) {
    headers.Authorization = `Bearer ${TOKEN}`;
  }

  const response = await fetch(`${APP_SERVER}${path}`, {
    method,
    headers,
    body: payload ? JSON.stringify(payload) : undefined,
  });

  const body = await response.json();
  if (!response.ok) {
    throw new Error(body.message ?? `Request failed with ${response.status}`);
  }
  return body;
}

async function main() {
  const tunnel = await api("POST", "/api/v1/tunnels", {
    name: "node-preview",
    type: "http",
    host: "localhost",
    port: 3000,
  });

  console.log("Tunnel URL:", tunnel.tunnel_url);
  console.log("Press Ctrl+C when you are done.");

  try {
    await new Promise((resolve) => process.once("SIGINT", resolve));
  } finally {
    await api("DELETE", `/api/v1/tunnels/${tunnel.id}`);
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});