aptunnel

Full-featured Aptible CLI wrapper — manage database tunnels with short aliases, plus alias-resolved passthrough for every Aptible command.

aptunnel dev-db          # open tunnel to dev database
aptunnel all             # open all configured tunnels
aptunnel dbs             # list all configured databases
aptunnel status          # see what's running
aptunnel uninstall       # clean uninstall (stops tunnels, removes config, runs npm uninstall)

Requirements

• Node.js 18+
• Aptible CLI installed and in your PATH

Install

npm install -g aptunnel

Quick Start

aptunnel init

The setup wizard first asks for an installation type:

Installation type:
  [1] Express  — login + auto-configure everything with defaults
  [2] Custom   — full interactive setup (ports, aliases, environments)

Select [1]:

Express install (recommended)

Enter your Aptible email + password (2FA prompt appears if enabled). aptunnel then:

1. Logs you in
2. Discovers all your environments and databases automatically
3. Assigns local ports starting at 55550
4. Uses each database's actual Aptible handle as its alias
5. Writes ~/.aptunnel/config.yaml

No further prompts. Run aptunnel config --set-port or aptunnel config --set-default afterwards to customise.

Custom install

Same login step, then full interactive setup:

1. Select which environments to include
2. Optionally customise port numbers and aliases for each database
3. Writes ~/.aptunnel/config.yaml

Example Custom session:

Available environments:
  [1] my-company-production-abc123
  [2] my-company-staging-def456
  [3] my-company-development-ghi789

Select environments (comma-separated numbers or "all") [all]: 1,3

  Databases in my-company-production-abc123:
  [1] mydb-prod  →  alias: mydb-prod  port: 55550  (postgresql)

  Customize aliases? (y/N) [N]: y
    Alias for mydb-prod [mydb-prod]: prod-db

The chosen install type is saved in config.yaml and used as the default on future aptunnel init runs.

Commands

Open a tunnel

aptunnel dev-db                    # open by alias
aptunnel dev-db --port=5432        # override port for this session
aptunnel dev-db --env=staging      # target a different environment
aptunnel dev-db --force            # auto-select a free port if configured port is busy

Output:

✔ dev-db tunnel opened
  Port:      55554
  Host:      localhost.aptible.in
  User:      aptible
  Password:  xxxxxxxxxx
  URL:       postgresql://aptible:[email protected]:55554/db
  PID:       12345

Close a tunnel

aptunnel dev-db --close
aptunnel all --close               # close all
aptunnel all --close --env=staging # close all in staging
aptunnel dev-db --close --force    # force-release port even if no PID file

Open all tunnels for an environment

aptunnel all                       # open all environments (warns on production)
aptunnel all --env=staging         # open all tunnels in a specific environment

List databases

aptunnel dbs                       # all configured databases
aptunnel dbs --env=staging         # filter by environment

Output:

ALIAS      DATABASE             TYPE        PORT    ENVIRONMENT
─────────────────────────────────────────────────────────────────────
dev-db     mydb-dev             postgresql  55550   dev
dev-redis  mydb-dev-redis       redis       55551   dev
stg-db     mydb-staging         postgresql  55552   staging

Status

aptunnel status
aptunnel status --watch            # live-refresh every 2 seconds

LOGIN STATUS
  User:   [email protected]
  Token:  valid (expires in 6d 12h)

TUNNELS

DATABASE                   PORT    TYPE   STATUS  UPTIME       PID    URL
────────────────────────────────────────────────────────────────────────────────────────────────────
── dev (my-env-development) ────────────────────────────────────────────────────────────────────────
db-dev (dev-db)       55554   pg     UP      02h15m30s    12345  postgresql://aptible:xxx@...
db-redis (dev-redis)  55555   redis  DOWN    -            -      -
── staging (my-env-staging) ────────────────────────────────────────────────────────────────────────
db-staging (stg-db)   55552   pg     DOWN    -            -      -

Login

aptunnel login                     # uses saved credentials, supports 2FA
aptunnel login [email protected] --password=secret
aptunnel login --lifetime=7d       # custom token lifetime (max: 7d)
aptunnel login --status            # show token info only

Config

aptunnel config                    # print config (password masked)
aptunnel config --raw              # include password
aptunnel config --set-port dev-db 5433
aptunnel config --set-default staging
aptunnel config --refresh          # re-discover environments/databases
aptunnel config --path             # print config file path

Uninstall

aptunnel uninstall                 # stop tunnels, remove config files, run npm uninstall
aptunnel uninstall --force         # also removes the entire ~/.aptunnel directory

aptunnel uninstall does the following in order:

1. Stops all running tunnels
2. Removes ~/.aptunnel/config.yaml and ~/.aptunnel/.credentials
3. Runs npm uninstall -g aptunnel

With --force, step 2 removes the entire ~/.aptunnel/ directory instead of individual files.

Configuration

Config lives at ~/.aptunnel/config.yaml. Your Aptible account password is stored separately in ~/.aptunnel/.credentials — AES-256-GCM encrypted with a key derived from your machine hostname and username (PBKDF2), and with file permissions restricted to your user (mode 600 on Unix, icacls on Windows). Existing plaintext credential files from earlier versions are read transparently and re-encrypted on next login.

version: 1

credentials:
  email: [email protected]

defaults:
  lifetime: 7d

environments:
  my-env-development:
    alias: dev
    databases:
      mydb-dev:
        alias: dev-db
        port: 55554
        type: postgresql
      mydb-redis:
        alias: dev-redis
        port: 55555
        type: redis

tunnel_defaults:
  start_port: 55550
  port_increment: 1

Overridable environment variables

Shell Completions

aptunnel completions install       # auto-detects your shell

Or manually:

# Bash — add to ~/.bashrc
source <(aptunnel completions bash)

# Zsh — add to ~/.zshrc
source <(aptunnel completions zsh)

# Fish
aptunnel completions fish > ~/.config/fish/completions/aptunnel.fish

Completions are dynamic — your actual database aliases appear in tab-completion.

Platform Support

Install Aptible CLI:

# macOS
brew install aptible/aptible/aptible

# Linux / WSL
curl -s https://toolbelt.aptible.com/install.sh | bash

# Windows
# Download from https://www.aptible.com/docs/cli

Aptible CLI Passthrough

aptunnel is a full wrapper around the Aptible CLI. Any Aptible command can be run through aptunnel — if aptunnel doesn't handle it natively, it is forwarded to aptible automatically.

Alias-resolved commands

For common database operations, aptunnel resolves your alias to the real Aptible handle and environment, so you never have to type them manually:

# Without aptunnel:
aptible db:backup mydb-production-abc123 --environment my-company-prod-env

# With aptunnel (alias configured in init):
aptunnel mydb-prod db:backup

Extra flags are passed through as-is:

aptunnel mydb-prod db:restart --container-size 1024

Bulk operations with all

Run any command on every configured database at once. Read-only commands run immediately; write operations ask for confirmation first:

aptunnel all db:backup              # backs up all databases (confirmation prompt)
aptunnel all db:backup --force      # skip confirmation
aptunnel all db:list                # list databases in all environments (no prompt)
aptunnel all db:backup --env=prod   # only databases in the prod environment

Verbatim passthrough

Any command aptunnel doesn't recognise is forwarded to the Aptible CLI verbatim — no alias resolution, no modifications:

aptunnel db:list --environment my-env       # forwarded as-is to aptible
aptunnel environment:list                   # forwarded as-is to aptible
aptunnel operation:follow 12345             # forwarded as-is to aptible

Tab completion is available for alias-resolved commands. For verbatim passthrough, use the Aptible CLI syntax directly.

How Tunnels Work

aptible db:tunnel is a blocking foreground process. aptunnel spawns it as a background process with stdio redirected to a log file (/tmp/aptunnel-<alias>.log), then saves the PID to /tmp/aptunnel-<alias>.pid.

The tunnel is considered open once aptible prints Connect at in the log (polled every 500 ms, 60 s timeout).

On aptunnel status, each PID file is checked to determine if the process is still alive.

When you close a tunnel (aptunnel dev-db --close), aptunnel kills the process and cleans up PID/log files.

Pressing Ctrl+C while a tunnel command is running closes any tunnels opened in that session before exiting. In status --watch mode, Ctrl+C exits the watch loop without affecting background tunnels.

Windows note: On Windows the tunnel process is not fully detached from the terminal session. If you close the terminal window while tunnels are running, they will be terminated. Re-open them with aptunnel <alias> or aptunnel all.

Troubleshooting

"Aptible CLI not found" — Install the Aptible CLI and make sure it's in your PATH. Run aptible version to verify.

"Token expired" — Run aptunnel login. aptunnel will attempt auto-relogin on tunnel failures, but a fresh login is the cleanest fix.

"Port already in use" — Another process is on that port. Use --force to let aptunnel auto-select the next free port, --port=<N> to pick one manually, or update the default with aptunnel config --set-port dev-db <N>.

"Config file is corrupted" — Delete ~/.aptunnel/config.yaml and re-run aptunnel init.

Tunnel fails silently — Check the log file: cat /tmp/aptunnel-<alias>.log.

aptunnel init hangs after email/password — This can happen if the terminal is not a TTY. Make sure you're running aptunnel directly in a terminal, not piped.

Contributing

See CONTRIBUTING.md for local dev setup, architecture overview, and the release process.

License

MIT — see LICENSE.

aptunnel-gui

Terminal GUI for aptunnel — visual frontend for managing Aptible database tunnels from your terminal.

aptunnel-gui          # launch the terminal GUI

Requirements

Before installing aptunnel-gui, make sure you have the following:

1. Node.js 18+

Download from nodejs.org or use a version manager:

# macOS / Linux — via nvm
nvm install 20
nvm use 20

# Windows — via nvm-windows
# https://github.com/coreybutler/nvm-windows

Verify:

node --version   # should print v18.x or higher

2. Aptible CLI

aptunnel-gui shells out to the Aptible CLI — it must be installed and available in your PATH.

# macOS
brew install aptible/aptible/aptible

# Linux / WSL
curl -s https://toolbelt.aptible.com/install.sh | bash

# Windows
# Download the installer from https://www.aptible.com/docs/cli

Verify:

aptible version

3. aptunnel 1.1.0+

aptunnel-gui manages your Aptible tunnels through aptunnel. If it's not installed or is outdated, aptunnel-gui will install/update it automatically on first launch.

To install manually:

npm install -g aptunnel

Verify:

aptunnel --version

Install

npm install -g aptunnel-gui

Then launch:

aptunnel-gui

On first launch, the setup wizard guides you through connecting to your Aptible account and configuring your environments.

First launch — setup wizard

The wizard runs automatically if no ~/.aptunnel/config.yaml is found. It:

1. Checks your aptunnel version (installs/updates if needed)
2. Detects existing config (offers to skip setup if already configured)
3. Authenticates with your Aptible account via aptunnel login
4. Fetches your environments and databases
5. Assigns aliases and port numbers
6. Detects database types (PostgreSQL, MySQL, Redis, Elasticsearch)
7. Installs the relevant database drivers

Usage

Dashboard

The main screen. Environments are collapsible rows. Each database shows its tunnel status, port, and last-seen time.

 aptunnel-gui  │  env: dev  │  2/4 tunnels up          aptunnel-gui v1.0.0
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
 ▼ dev    (2/3 up)    [↑ All]  [↓ All]  [⟳]  [hide ↯]

      name               type       status    port       last seen
      ─────────────────  ─────────  ────────  ─────────  ──────────
  ●  dev-db             postgresql  UP       :55554     14:32   [→]
  ●  dev-redis          redis       DOWN     :55555     —       [→]
  ●  dev-elastic        elastic     CONN     :55556     14:33   [→]

 ▶ staging  (0/1 up)
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
 [↑↓] nav  [Enter] expand  [o] open  [c] close  [p] port  [h] hide  [Ctrl+C] quit

Status dot colors: ● green = UP, red = DOWN, yellow = connecting.

DB Detail

Opens with Enter or → on a database row. Shows tunnel controls, togglable credentials, and a schema browser (tables, views, indexes, triggers, functions).

Port editor

Press p on any database to open the 3-step port change modal: enter new port → confirm reconnect → optionally save as default.

Logs

Press l from the dashboard. Scrollable log of all tunnel events, schema loads, errors, and background activity. Filterable by environment, level, and date. Exportable to file.

Settings

Press s from the dashboard. Configure polling interval, auto-open behavior, background preload, log retention, name truncation, and more.

Keyboard reference

Dashboard

DB Detail

Settings

Logs

Storage

aptunnel-gui stores its data in ~/.aptunnel-gui/:

~/.aptunnel-gui/
  settings.json          — preferences
  cache/
    <env-alias>/
      <db-alias>.json    — cached schema data per database
  logs/
    YYYY-MM-DD.log       — daily log files (auto-rotated)

aptunnel's own config stays at ~/.aptunnel/config.yaml — aptunnel-gui reads it but only modifies it through the built-in Config Editor screen.

Platform support

Contributing

See CONTRIBUTING.md for how to clone, set up, and run the project locally.

Donate

If this tool saves you time, consider supporting development:

• GitHub Sponsors
• Ko-fi

License

MIT — see LICENSE.

claude-api-proxy

Anthropic API key rotation proxy for Claude Code — seamlessly switch keys when one account's quota runs out.

claude-api-proxy setup      # add your API keys
claude-api-proxy            # start proxy + launch Claude Code
claude-api-proxy status     # see which key is active

How it works

claude-api-proxy runs a local HTTP proxy on port 3131. It starts Claude Code as a child process with ANTHROPIC_BASE_URL pointing at the proxy. Every API request is forwarded to api.anthropic.com with the currently active key injected.

When a quota or credit exhaustion error is detected (402, 429, 529 / credit_balance_too_low, rate_limit_error, overloaded_error), the proxy silently rotates to the next configured key and retries — without interrupting your Claude Code session.

[claude-api-proxy] ⚡ KEY ROTATED: work → personal

If all keys are exhausted, the original error is passed back to Claude Code unchanged.

Requirements

• Node.js 18+
• Claude Code installed and in your PATH

Install

npm install -g claude-api-proxy

Quick start

1. Add your API keys:

claude-api-proxy setup

[claude-api-proxy] Setup — Add your Anthropic API keys
Keys are stored in ~/.claude-api-proxy.json

Key label (e.g. "work", "personal") [leave blank to finish]: work
API key for "work" (sk-ant-...): sk-ant-api03-...
  ✓  Added key "work"

Add another key? (y/N): y
Key label (e.g. "work", "personal") [leave blank to finish]: personal
API key for "personal" (sk-ant-...): sk-ant-api03-...
  ✓  Added key "personal"

Add another key? (y/N): n

✓ Saved 2 key(s) to ~/.claude-api-proxy.json

2. Start the proxy and Claude Code:

claude-api-proxy

That's it. Claude Code launches automatically with the proxy configured. When the first key hits its quota, the proxy rotates to the next key transparently.

Commands

claude-api-proxy setup

Interactive wizard to add API keys. Stores them in ~/.claude-api-proxy.json.

claude-api-proxy status

List all configured keys with their labels and which one is currently active.

[claude-api-proxy] Configured API keys:

  [1] work                 sk-ant-api03...xxxx ← active
  [2] personal             sk-ant-api03...yyyy

claude-api-proxy

Start the proxy on port 3131 and launch claude with the correct environment variables injected (ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY).

claude-api-proxy --no-launch

Start the proxy only. Useful if you want to launch Claude Code manually or connect another tool.

claude-api-proxy --no-launch
# Proxy running. Launch claude manually:
#   ANTHROPIC_BASE_URL=http://127.0.0.1:3131 ANTHROPIC_API_KEY=proxy claude

claude-api-proxy --port <n>

Use a custom port instead of the default 3131.

claude-api-proxy --port 8080

claude-api-proxy --verbose / -v

Log each forwarded request and which key is being used to stderr.

[claude-api-proxy] → POST /v1/messages (key: work)

Key storage

Keys are stored in ~/.claude-api-proxy.json:

{
  "keys": [
    { "label": "work",     "key": "sk-ant-...", "active": true },
    { "label": "personal", "key": "sk-ant-...", "active": true }
  ],
  "currentIndex": 0
}

The proxy rotates currentIndex forward on exhaustion. After cycling through all keys, it resets. The file is updated on disk after each rotation so the active key persists across restarts.

Platform support

Contributing

See CONTRIBUTING.md for local dev setup, architecture notes, and the release process.

License

MIT — see LICENSE.

Noteward

Smart daily notes reminder with automatic sensitive data protection.

Noteward watches your notes folder, encrypts sensitive data automatically, syncs to a server, and sends you a daily AI-powered summary via Slack or Discord — without ever exposing your secrets.

How It Works

Your notes folder
  └── watcher.py        ← watches for changes
        │ detects secrets → encrypts locally
        │ syncs files (without secrets) → server
        └── Server
              ├── Daily summary → Slack / Discord
              └── Bot commands  → !get <secret-name>

Security model:

• Secrets are encrypted locally with a data_key
• data_key is wrapped with your master password (never stored plain)
• Only ciphertext ever leaves your machine
• Server holds key in RAM only (/dev/shm) — lost on reboot
• Recovery key stored locally as your offline backup

Quick Start

Requirements: Python 3.8+

curl -fsSL https://raw.githubusercontent.com/Uruba-Software/noteward/main/install.py -o /tmp/nw-install.py && python3 /tmp/nw-install.py

That's it. The installer handles everything else (including Docker if missing).

The installer will ask you:

1. Which folder to watch
2. Local or remote server
3. Slack or Discord
4. Claude, ChatGPT, or Ollama
5. Daily summary time
6. Master password

That's it. Then start watching:

cd ~/your-notes-folder
python watcher.py

Bot Commands

In your Slack/Discord channel:

Automatic Secret Detection

Write anything in your notes — sensitive values are detected and encrypted automatically:

# Before saving:
github token: ghp_abc123...
api key: sk-ant-api03-...
my server password: s3cr3t!

# After watcher processes it:
github token: [secret:github-token]
api key: [secret:anthropic-api-key]
my server password: [secret:my-server-password]

To bypass detection on a line, add # nosecret:

example token: not-a-real-secret # nosecret

Recovery

If you forget your master password:

cd ~/your-notes-folder
python watcher.py --recover

This uses the recovery key at .noteward/recovery.key. Keep this file backed up somewhere safe (password manager recommended).

Configuration

Config lives at {notes_dir}/.noteward/config.yml. See config.example.yml for all options.

Supported Providers

AI: Claude (Anthropic) · ChatGPT (OpenAI) · Ollama (local)

Notifications: Slack · Discord

Sources (current): Notes files

Sources (roadmap): GitHub · Jira · Email

License

MIT