Remote API - Expose Local API for External Testing via Aitun Tunnel

When to Use

Use this skill when:

• You built a REST API, GraphQL endpoint, or any HTTP API locally and need someone to test it
• You want to share a local API with a frontend developer, QA team, or integration partner
• You need a public API endpoint for a client app, mobile app, or third-party tool to call
• You are developing an API and want to test it with external tools like Postman, curl, or Swagger UI
• You need to register a local API with an API gateway or service mesh

Do NOT use this skill when:

• The API is already deployed to a public server
• You only need to test the API locally (no tunnel needed)
• You want to send files rather than serve an API (use sendfile instead)

Instructions

Step 1: Install aitun

pip install aitun

Or verify it is already installed:

which aitun || pip show aitun

Step 2: Start the local API service

Start your API server on a local port. Examples:

# Flask REST API
flask run --port 8080 --host 0.0.0.0 &

# FastAPI
uvicorn main:app --host 0.0.0.0 --port 8080 &

# Express.js
node server.js --port 8080 &

# Django
python manage.py runserver 0.0.0.0:8080 &

# Any HTTP API on any port

Verify it is running locally:

curl -s http://localhost:8080/health || echo "API not responding"

Step 3: Create a tunnel

Expose the API to the internet:

aitun -p 8080 &
AITUN_PID=$!
sleep 3

The output will contain the public URL, e.g.:

• https://aitun.cc/abc123

Step 4: Share the API URL

Tell the user or integration partner the public API base URL:

Your API is now publicly accessible at: https://aitun.cc/abc123

Example endpoints:
- GET  https://aitun.cc/abc123/health
- GET  https://aitun.cc/abc123/api/users
- POST https://aitun.cc/abc123/api/users

Test with curl:
  curl https://aitun.cc/abc123/health

This tunnel expires in 24 hours.

Step 5: Test and iterate

You or your users can now test the API with any HTTP client:

# Quick health check
curl -s https://aitun.cc/abc123/health

# GET request
curl -s https://aitun.cc/abc123/api/items

# POST request with JSON body
curl -X POST https://aitun.cc/abc123/api/items \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "value": 42}'

Continue developing and restarting the API server locally — the tunnel stays active as long as the aitun process runs.

Step 6: Clean up

When testing is complete, stop the servers:

kill $AITUN_PID 2>/dev/null

CLI Reference

The aitun command (installed via pip install aitun) accepts these flags:

Notes

• Free tunnels use proxy address mode (path-based URL like aitun.cc/abc123), NOT subdomains
• Free tunnels expire after 24 hours, auto-renewed on restart
• For a permanent API endpoint (e.g., api.t.aitun.cc), register at https://aitun.cc
• CORS headers may need to be configured on your API server to allow cross-origin requests from browsers
• If your API uses WebSocket, the tunnel supports WebSocket proxying
• For TCP-based APIs (databases, gRPC), use the --tcp-ports flag with an auth token
• All traffic is encrypted end-to-end
• Rate limiting and authentication should be implemented in your API server for security