Tunnels & Public Sharing

Creating Tunnels

Tunnels expose a local port publicly via a secure URL, enabling you to share previews, reports, and services externally.

# Create a tunnel to a local port
aiter tunnel create --localPort 3000 --label "Preview" --expiresIn 3600

# Associate tunnel with a project
aiter tunnel create --localPort 8080 --projectId project-123 --label "API" --expiresIn 7200

Parameters:

Param	Required	Description
localPort	Yes	Local port to expose
projectId	No	Associated project ID
label	No	Human-readable label
expiresIn	No	Expiry in seconds (default: 3600 = 1 hour)

Response:

{
  "success": true,
  "data": {
    "id": "tunnel-abc123",
    "url": "https://abc123.tunnel.aiter.app",
    "localPort": 3000,
    "label": "Preview",
    "expiresAt": "2024-01-15T11:30:00Z",
    "status": "active"
  }
}

---

Managing Tunnels

# List all active tunnels
aiter tunnel list

# Close a specific tunnel
aiter tunnel close --id tunnel-abc123

# Close all tunnels
aiter tunnel close-all

Constraints:

• Maximum 3 concurrent tunnels
• Default expiry: 1 hour (3600 seconds)
• Max expiry: 24 hours (86400 seconds)
• Tunnels auto-close when they expire

---

Share Pattern: File Server + Tunnel

The most common pattern is sharing project files (HTML reports, previews) via tunnel:

Step 1: Start the file server

# Start file server for the project
aiter server start --projectId project-123

# Get the local URL for a specific file
LOCAL_URL=$(aiter server url --projectId project-123 --filePath report.html | jq -r '.data.url')
# Returns: http://localhost:3456/report.html?token=xxx

# Extract the port
PORT=$(echo $LOCAL_URL | grep -oP ':\K\d+')

Step 2: Create tunnel to file server

# Create tunnel to the file server port
TUNNEL=$(aiter tunnel create --localPort $PORT --projectId project-123 --label "Report" --expiresIn 3600)
PUBLIC_URL=$(echo $TUNNEL | jq -r '.data.url')

Step 3: Share the URL

# Share via IM
aiter message send --channel channel-abc --text "Report ready: $PUBLIC_URL" --format markdown

# Or via notification
aiter notify send --message "Report available at: $PUBLIC_URL (expires in 1 hour)"

Full share workflow (combined)

# 1. Generate the report/file first
# (done by agent — create HTML, write to project directory)

# 2. Start server and create tunnel
SERVER_INFO=$(aiter server start --projectId $PROJECT_ID)
PORT=$(echo $SERVER_INFO | jq -r '.data.port')

TUNNEL_INFO=$(aiter tunnel create --localPort $PORT --label "Shared Report" --expiresIn 3600)
PUBLIC_URL=$(echo $TUNNEL_INFO | jq -r '.data.url')
FILE_URL="${PUBLIC_URL}/report.html"

# 3. Share
aiter message send --channel $CHANNEL_ID --text "**Report Ready**\n\nView it here: $FILE_URL\n\nLink expires in 1 hour." --format markdown

---

Tunnel Lifecycle

Create → Active → [Expiry or Manual Close] → Closed

Best practices:

• Always set an expiry (don't leave tunnels open indefinitely)
• Use descriptive labels so you know what each tunnel serves
• Close tunnels when sharing is complete (don't wait for expiry)
• Check aiter tunnel list before creating new ones (3 max)
• Log tunnel creation in .aiter/memory/journal.md for audit trail

---

Security Considerations

• Tunnel URLs are publicly accessible — anyone with the URL can access the content
• File server tokens are included in local URLs but NOT in tunnel URLs (tunnel proxies handle auth)
• Never tunnel ports that expose sensitive services (databases, admin panels) without additional auth
• Set short expiry times for sensitive content
• Close tunnels immediately after the recipient confirms receipt