Environment Variables

Q: What happens if I set both the flag and the environment variable?

The flag wins. Resolution runs flag, then variable, then _FILE variable, and stops at the first one with a value. This lets a service set the variable permanently while you override it for one run.

Q: Why does the agent refuse to read my token file?

The file has to be a regular file, mode 0600 or stricter, and owned by the account running the agent. A symlink is refused, and so is a file owned by somebody else, even at 0600 . The error names the file and the mode it actually had. Fix it with chmod 0600 and chown .

Q: Can I put an environment variable inside a config file?

Yes, with ${env.VAR} . It is substituted when the file is read, so the token stays in the environment and the file stays committable. A reference to a variable that is unset stops the run and names every missing variable at once.

Q: How do I turn off the colours in the live panel?

Set NO_COLOR to any value, or set TERM=dumb for plain output. In the other direction, COLORTERM=truecolor gives the panel 24-bit colour. The agent also drops to plain log lines on its own when nothing is attached to a terminal.

Q: Where does the agent store credentials, and can I move them?

Under ~/.localport , with directories at 0700 and files at 0600 . Set LOCALPORT_HOME to move them. That is the setting to use for a system account with no home directory. Only localport setup and localport login write anything, and a token-authenticated tunnel stores nothing.

Q: Which variable does a CI job need?

Usually none. On a platform the agent recognises, localport access --audience uses the token the platform already mints and no secret is stored anywhere. On a platform it does not recognise, put that token in LOCALPORT_OIDC_TOKEN . See CI/CD with OIDC .

Summary

Every setting you can pass as a flag can also come from the environment, and every secret can come from a file instead. That is how you run the agent on a server, in a container, or in CI without a token ever appearing in a command line or a process list.

Which environment variables does the agent read?#

Variable	Applies to	What it does
`LOCALPORT_TOKEN`	Tunnels	Tunnel token, instead of `--token`
`LOCALPORT_TOKEN_FILE`	Tunnels	File to read the tunnel token from
`LOCALPORT_SETUP_TOKEN`	`setup`	Setup key, instead of the positional argument
`LOCALPORT_SETUP_TOKEN_FILE`	`setup`	File to read the setup key from
`LOCALPORT_IDENTITY`	`access`, `identity`	Which stored credential to present
`LOCALPORT_HOME`	all	Where credentials are stored. Defaults to `~/.localport`
`LOCALPORT_P12_PASSWORD`	`access`	Password for a PKCS#12 file. Point `--p12-pass-env` at a different variable to rename it
`LOCALPORT_OIDC_AUDIENCE`	`access`	OIDC audience, instead of `--audience`
`LOCALPORT_OIDC_TOKEN`	`access`	A workload token from a CI platform the agent does not detect. Checked first when present
`NO_COLOR`	Tunnels	Set to anything to turn colour off
`COLORTERM`	Tunnels	`truecolor` or `24bit` for 24-bit colour in the live panel
`TERM`	Tunnels	`dumb` forces plain output

Which source wins#

The flag, then the variable, then the file. Every secret resolves in that order.

--token          highest
LOCALPORT_TOKEN
LOCALPORT_TOKEN_FILE   lowest

So a systemd unit can set LOCALPORT_TOKEN_FILE for normal operation, and you can still override it once on the command line without editing the unit.

--identity follows the same shape, with one addition. When no selector is given and a person is at the terminal, the agent shows a picker. A selector that matches nothing, or matches several credentials, is an error and never a prompt.

--identity  >  LOCALPORT_IDENTITY  >  interactive picker

How to keep a token out of the process list#

Use the _FILE form. An argument on the command line appears in shell history, in ps output and in /proc, where every other account on the machine can read it.

export LOCALPORT_TOKEN_FILE=/etc/localport/token
localport http 3000

The variable itself is second best on a shared machine, since /proc/<pid>/environ exposes it to root and to anything running as the same user. The file form is what systemd's LoadCredential= and Docker secrets produce, and what the service templates use.

A file holding a secret is held to the same rules as a private key. It must be a regular file, mode 0600 or stricter, and owned by the account running the agent. Anything else is refused, with the mode it actually had:

/etc/localport/token has too-open permissions 0644 (want 0600 or stricter)

Secret values are stripped from error messages before they are printed, so a failure path cannot put a token in a log.

How to use a variable inside a config file#

Write ${env.VAR}. References are substituted when the file is read, so a config file you commit holds no secrets.

version: 1
token: ${env.LOCALPORT_TOKEN}
endpoints:
  - name: api
    url: http://localhost:3000

export LOCALPORT_TOKEN=tok_...
localport --config localport.yaml

A reference to a variable that is unset or empty stops the run, and the error names every one that was missing:

undefined env vars: LOCALPORT_TOKEN, DB_PORT

The full file format is on the Configuration page.

Where credentials are stored#

Under ~/.localport, with directories at mode 0700 and files at 0600. Set LOCALPORT_HOME to move that somewhere else.

A system account usually has no home directory to write to. The service templates set LOCALPORT_HOME explicitly for that reason. A tunnel that authenticates with a token alone stores nothing.

Frequently asked questions#

Can I use environment variables instead of flags for everything?

For secrets and credential selection, yes. Tunnel tokens, setup keys, PKCS#12 passwords, OIDC audiences and the identity selector all have a variable. Options that shape a single run, such as the protocol, the port and the region, are flags or config file fields. The CLI reference lists every flag.

What happens if I set both the flag and the environment variable?

The flag wins. Resolution runs flag, then variable, then _FILE variable, and stops at the first one with a value. This lets a service set the variable permanently while you override it for one run.

Why does the agent refuse to read my token file?

The file has to be a regular file, mode 0600 or stricter, and owned by the account running the agent. A symlink is refused, and so is a file owned by somebody else, even at 0600. The error names the file and the mode it actually had. Fix it with chmod 0600 and chown.

Is the environment safer than the command line?

Better, and not by much. The command line is visible to every account on the machine through ps and /proc. The environment is visible to root and to anything running as the same user through /proc/<pid>/environ. A _FILE variable pointing at a 0600 file is the one that holds up on a shared machine.

Can I put an environment variable inside a config file?

Yes, with ${env.VAR}. It is substituted when the file is read, so the token stays in the environment and the file stays committable. A reference to a variable that is unset stops the run and names every missing variable at once.

How do I turn off the colours in the live panel?

Set NO_COLOR to any value, or set TERM=dumb for plain output. In the other direction, COLORTERM=truecolor gives the panel 24-bit colour. The agent also drops to plain log lines on its own when nothing is attached to a terminal.

Where does the agent store credentials, and can I move them?

Under ~/.localport, with directories at 0700 and files at 0600. Set LOCALPORT_HOME to move them. That is the setting to use for a system account with no home directory. Only localport setup and localport login write anything, and a token-authenticated tunnel stores nothing.

Which variable does a CI job need?

Usually none. On a platform the agent recognises, localport access --audience uses the token the platform already mints and no secret is stored anywhere. On a platform it does not recognise, put that token in LOCALPORT_OIDC_TOKEN. See CI/CD with OIDC.