Getting Started

Quickstart

Create a secure, public URL to your local app in under 60 seconds.

1. Install the agent

Pick your platform on the right and run the install command.

2. Authenticate

Save your API token to authenticate the agent. Tokens are generated from the dashboard.

3. Launch your first endpoint

Share your local app on port 3000 with a predictable subdomain. For a step-by-step walkthrough, see how to expose localhost to the internet, or put a custom domain on localhost to serve your own domain over HTTPS.

Installation

Pick your platform. The agent is a single static binary — no runtime dependencies.

Homebrew is the easiest install path on macOS.

Use the official Windows package via winget.

The install script auto-detects your distribution and architecture.

Run the agent as a container from ghcr.io/ngris-edge/ngris (multi-arch amd64/arm64). Use --network host so it can reach services on localhost.

Updating the agent

Update with the tool you installed with, then restart ngris — a running agent keeps using the binary it started with. Check the result with ngris --version.

Minimum supported version

Ngris can also set a minimum agent version. An agent below it is refused the same way, with a message that names your version and the minimum, for example This ngris agent (<your version>) is older than the minimum supported version (<minimum>). Update it: https://ngris.com/install.

The minimum applies to the CLI's own commands too. ngris deploy, ngris apps … (including ngris apps env and ngris apps cron) and every other command that calls the ngris API are refused with 426 and a message such as This ngris CLI (v<your version>) is older than the minimum supported version <minimum>. Update: https://ngris.com/install. Update the agent and run the command again.

Homebrew, winget, install script

Homebrew and winget upgrade the package in place. The install script always installs the latest release (set NGRIS_VERSION to pin one), so running it again updates the agent. If ngris --version still shows the old version afterwards, an older copy comes first on your PATH: find it with command -v ngris, or reinstall into that directory with NGRIS_INSTALL_DIR.

Docker & Kubernetes

Pull the image again and recreate the container. An image pinned to an older tag (for example ghcr.io/ngris-edge/ngris:0.4.1) has to move to the new release.

Authentication

Login once per device, revoke from the dashboard any time.

Agent Auth Token

The agent reads its token from ngris auth output or the API_TOKEN environment variable.

Config File

For repeatable deployments, store the token in a config.yaml beside the agent.

Key authentication (Preview)

Instead of a token, the agent can log in to its tunnel with a key, like SSH. The private key stays on your machine and you never paste it anywhere. Needs an agent newer than v0.4.2.

1. Create a key just for ngris: mkdir -p ~/.config/ngris && ssh-keygen -t ed25519 -N "" -f ~/.config/ngris/agent_key. On Windows, use the Windows PowerShell block.
2. Register it. In the dashboard, open Security → Agent keys and click Upload key. Run the command it shows, ngris key sign <code>, and paste the output. The key then logs in as you, in that account.
3. Use it: ngris auth --private-key-file ~/.config/ngris/agent_key.
4. Start a tunnel as usual, for example ngris http 3000 --url myapp.ngris.com.

You can also set the key in config.yaml, or pass --auth-method key --private-key-file <file> to a tunnel command. Environment variables can't set it: in a container, mount the key file and a config file, or pass the flags.

What still needs a token

A key logs in tunnels only. Keep a token for:

• app commands: apps, deploy, env, cron, promote, rollback, logs
• edge protection set from the agent: --basic-auth, --mutual-tls / --client-ca, --traffic-policy and its shorthand flags, webfm --rw, and the same settings in the config file. With any of them, the agent logs in with its token; without a token it doesn't start.
• removing endpoint auth an earlier run set from the agent (or remove it in the dashboard)

Protection you set on an endpoint in the dashboard works with a key too.

Key and token together

If a token is also configured, it stays as a backup. The key goes first after ngris auth --private-key-file (it sets method: key), otherwise the token. If the first one is not accepted (for example, a deleted key), the agent tries the other once and prints a warning. Use a key and a token of the same account. For key-only login, remove the token from the config and delete it in the dashboard. A token kept only as a backup is deleted after 90 days unused, like any token.

Limits

• Keys: ed25519 (recommended) or RSA with 2048 to 4096 bits.
• Not supported: keys with a passphrase, hardware security keys, ECDSA keys, keys held only in ssh-agent, and PuTTY .ppk files (convert them with PuTTYgen).
• A key can be registered once on ngris. For a second account, create a second key.
• A key opens any endpoint of its account. To limit an agent to one endpoint, use a token restricted to it.
• The Kubernetes operator and the Python SDK use tokens only.
• Networks that inspect encrypted traffic (TLS-inspecting proxies) block key login. Use a token there.
• Register keys in the dashboard or with an API key. Assistants connected through MCP, and Iris, can't register keys.

Good to know

• Use the key only for ngris, not for SSH logins.
• Deleting a key stops new logins. An agent already connected stays up until it reconnects.
• When a member leaves the account, their keys are deleted.
• Members who can see the account's tokens can see its keys; members who can manage endpoints can delete any of them.
• Keys don't expire.

Troubleshooting

• passphrase-protected: create a new key with the command in step 1. On Windows, press Enter twice when asked for a passphrase.
• permissions … are too open: run chmod 600 ~/.config/ngris/agent_key.
• PuTTY .ppk key: in PuTTYgen, use Conversions → Export OpenSSH key and point the agent at the exported file.
• already registered: the key is in another account or belongs to another member. Delete it there, or create a new key.
• does not match: open Upload key in the account you want, run its command again unchanged, and paste the new output.
• The key type or size isn't supported, or the key can't be used: create a new key with the command in step 1.
• key login refused when a tunnel starts: the key was deleted or isn't registered in this account. The agent prints Using key SHA256:… at start; that fingerprint must be in Security → Agent keys.

Your First Endpoint

Expose an HTTP service and share a stable URL.