Tunnels

# Bring the tunnel online and forward to your local server.
listener = inkbox.tunnels.connect(
    name=identity.agent_handle,
    forward_to="http://localhost:8080",
)
print(listener.public_url)  # https://my-agent.inkboxwire.com
listener.wait()  # blocks until SIGINT / SIGTERM

// connect() lives on a Node-only subpath because it pulls in
// node:http2, node:tls, and node:fs. The main package entry stays
// browser-safe.
import { connect } from "@inkbox/sdk/tunnels/connect";

const listener = await connect(inkbox, {
  name: identity.agentHandle,
  forwardTo: "http://localhost:8080",
});
console.log(listener.publicUrl);  // https://my-agent.inkboxwire.com
await listener.wait();  // resolves on clean close, throws on fatal

# Any ASGI app works — pass the app callable as forward_to.
# Example with FastAPI:
from fastapi import FastAPI

app = FastAPI()

@app.post("/webhook")
async def webhook(payload: dict):
    return {"ok": True, "received": payload}

listener = inkbox.tunnels.connect(name=identity.agent_handle, forward_to=app)
listener.wait()

// Pass a Fetch-API handler: (req, ctx) => Response | Promise<Response>.
import { connect } from "@inkbox/sdk/tunnels/connect";

const listener = await connect(inkbox, {
  name: identity.agentHandle,
  handler: async (req, ctx) => {
      const url = new URL(req.url);
      if (url.pathname === "/webhook" && req.method === "POST") {
          const payload = await req.json();
          return Response.json({ ok: true, received: payload });
      }
      return new Response("not found", { status: 404 });
  },
});
await listener.wait();

# ASGI handles HTTP and WebSocket through the same app callable.
# Use any ASGI framework that supports WS (FastAPI, Starlette, etc.).
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def ws(socket: WebSocket):
    await socket.accept()
    while True:
        msg = await socket.receive_text()
        await socket.send_text(f"echo: {msg}")

listener = inkbox.tunnels.connect(name=identity.agent_handle, forward_to=app)
listener.wait()

// In TypeScript, WebSockets are a separate handler from HTTP.
// You still need an HTTP path (forwardTo or handler) alongside.
import { connect } from "@inkbox/sdk/tunnels/connect";

const listener = await connect(inkbox, {
  name: identity.agentHandle,
  forwardTo: "http://localhost:8080",  // or handler: ...
  wsHandler: async (ws) => {
      await ws.accept();
      for await (const msg of ws) {
          await ws.send(`echo: ${msg}`);
      }
  },
});
await listener.wait();

# Sync — for scripts and CLIs. Blocks the calling thread until
# SIGINT / SIGTERM, then drives a clean shutdown.
listener = inkbox.tunnels.connect(name=identity.agent_handle, forward_to="http://localhost:8080")
listener.wait()

# Async — when you're already inside an event loop.
import asyncio

async def main():
    listener = inkbox.tunnels.connect(
        name=identity.agent_handle,
        forward_to="http://localhost:8080",
    )
    try:
        await listener.serve_forever()
    finally:
        await listener.aclose()

asyncio.run(main())

// listener.wait() resolves on clean close (Ctrl+C / SIGTERM, or
// an explicit close()) and throws if the runtime hit a fatal error.
const listener = await connect(inkbox, {
  name: identity.agentHandle,
  forwardTo: "http://localhost:8080",
});

try {
  await listener.wait();
} finally {
  await listener.close();
}

// If your host process owns shutdown, opt out of the auto-installed
// signal handlers and drive close() yourself.
const headless = await connect(inkbox, {
  name: identity.agentHandle,
  forwardTo: "http://localhost:8080",
  installSignalHandlers: false,
});

# Deleting the identity cascades to the linked mailbox and tunnel.
identity = inkbox.get_identity("sales-bot")
identity.delete()

// Deleting the identity cascades to the linked mailbox and tunnel.
const identity = await inkbox.getIdentity("sales-bot");
await identity.delete();

# List every tunnel in your org
for t in inkbox.tunnels.list():
    print(t.tunnel_name, t.status, t.currently_connected)

# Fetch one by id, including a live currently_connected flag
t = inkbox.tunnels.get(tunnel_id)

# Tag a tunnel with free-form metadata for your own tracking
inkbox.tunnels.update(
    tunnel_id,
    metadata={"purpose": "webhooks", "owner": "my-agent"},
)

// List every tunnel in your org
for (const t of await inkbox.tunnels.list()) {
  console.log(t.tunnelName, t.status, t.currentlyConnected);
}

// Fetch one by id, including a live currentlyConnected flag
const t = await inkbox.tunnels.get(tunnelId);

// Tag a tunnel with free-form metadata for your own tracking
await inkbox.tunnels.update(tunnelId, {
  metadata: { purpose: "webhooks", owner: "my-agent" },
});