Chara Tunnel

Chara Tunnel is a lightweight, easy-to-use tunneling service that exposes your local development servers to the internet through custom subdomains. Similar to tools like ngrok or localtunnel, Chara Tunnel allows you to share your work, test webhooks, and demo applications without deploying.

Features

• 🌐 Expose local servers to the internet with custom subdomains
• 🔄 Stream HTTP requests and responses
• 🧩 Modify response content on-the-fly via configurable replacements
• 🔒 WebSocket-based secure communication
• 🔍 Detailed logging for troubleshooting

Installation

# Install globally
bun add -g @chara-codes/tunnel

# Or use with bunx
bunx @chara-codes/tunnel [command]

# Or install locally
bun add @chara-codes/tunnel

Usage

Chara Tunnel consists of two parts: a server component that receives internet traffic and a client component that connects to the server and forwards requests to your local application.

Start a tunnel server

tunnel server --port 1337 --domain chara-ai.dev --controlDomain control.chara-ai.dev

Connect a local server

tunnel client --port 3000 --host localhost --remoteHost control.chara-ai.dev --subdomain myapp.chara-ai.dev

This will make your local server available at myapp.chara-ai.dev.

Using a random domain

If you don't specify a subdomain when connecting a client, the server will generate a random one for you:

tunnel client --port 3000 --host localhost --remoteHost control.chara-ai.dev

You'll receive output similar to:

✓ Connected to tunnel server!
✓ Tunnel established! Your local server is now available at:
  https://random-words-123456.chara-ai.dev

Command Options

Server Command

tunnel server [options]

| Option | Description | Default | |--------|-------------|---------| | --port, -p | Port to listen on | 1337 | | --domain | Root domain for generating subdomains | chara-ai.dev | | --controlDomain | Control domain for WebSocket connections | control.chara-ai.dev | | --debug, -D | Enable debug logging | false | | --configFile, -c | Path to a JSON configuration file for replacements | - |

Client Command

tunnel client [options]

| Option | Description | Default | |--------|-------------|---------| | --port, -p | Local port to forward | 3000 | | --host, -h | Local host to forward | localhost | | --remoteHost, -r | Remote tunnel server host | control.localhost:1337 | | --secure, -s | Use secure WebSocket connection (wss://) | true | | --subdomain, -d | Desired subdomain (random if not specified) | - | | --debug, -D | Enable debug logging | false |

Content Replacements

Chara Tunnel can modify HTML responses on-the-fly by applying text replacements. This is useful for injecting scripts, modifying content, or adding analytics.

Create a config file (e.g., config.json):

{
  "replacements": [
    {
      "pattern": "</body>",
      "replacement": "<script>console.log('Injected via Chara Tunnel');</script></body>"
    },
    {
      "pattern": "<title>(.*?)</title>",
      "replacement": "<title>$1 [Dev]</title>"
    }
  ]
}

Then start the server with:

tunnel server --configFile config.json

Use Cases

• Development & Testing: Expose your local dev server to the internet
• Demos & Sharing: Share your work with clients or team members
• Webhook Testing: Test webhook integrations with third-party services
• Mobile App Testing: Test your APIs with mobile applications over the internet
• Content Injection: Add scripts or stylesheets to any web page for testing

Programmatic Usage

import { TunnelClient, startServer } from '@chara-codes/tunnel';

// Start a client
const client = new TunnelClient({
  port: 3000,
  host: 'localhost',
  remoteHost: 'control.chara-ai.dev',
  subdomain: 'test.chara-ai.dev'
});

await client.connect();

// Start a server
startServer({
  port: 1337,
  domain: 'chara-ai.dev',
  controlDomain: 'control.chara-ai.dev',
  replacements: [
    { pattern: '</body>', replacement: '<script>console.log("Hello");</script></body>' }
  ]
});

License

Apache License 2.0

Copyright (c) 2025 Chara Codes

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See the main LICENSE file for details.