Ephemeral Runs
Run conflux without writing anything to disk. The credential lives and renews in memory, and it is gone when the run ends. In proxy mode, you don't need root.
- Needs
- Root for up; nothing for proxy
- Writes
- No files and no boot service
- Keeps
- Nothing after the run ends
When to Use It
Use an ephemeral run when a machine should be on the overlay only while something is running. Examples are a CI job, a container, a Kubernetes pod, a laptop that joins for one session, or a host whose disk you don't trust with a key.
To start one, add --ephemeral to conflux up or conflux proxy. Conflux then runs a single anchor in the foreground, using a credential held in memory:
- It doesn't read or write the machine's own files:
conflux.json,manifest.b64andstate.jsonare untouched, and no boot service is registered. - The credential passes from conflux's memory to anchorctl's standard input, and from there to anchord, which also keeps it in memory.
- When anchord stops, the identity, the credential, the overlay address and the run's directory are all gone.
conflux proxy --ephemeraldoesn't need root, systemd or a volume.
An ephemeral run is a way to run either mode, not a separate mode. It never changes the mode the machine is configured for.
Starting a Run
Run
uporproxywith--ephemeral. The run enrols in memory, the same wayupenrols, and stays in the foreground:$ sudo conflux up --ephemeral --taint brhk-2mq9-tzva-6pjs-k4xe-nw7d-qf --ipv4 10.128.0.9/24 Starting an ephemeral anchor: nothing is saved, and when it stops nothing of it remains. anchord: … anchord listening … enrolling, into memory alone anchor anchor6btpa3gn6w4stipba4hekzho7caw6srfyy5puvbz7mfanaiept5a overlay fd80:c4b9:99ae:4411:c531:fd4f:754f:f08a/48 ipv4 10.128.0.9/24 interface anchor6btpa3gn6 taint brhk-2mq9-tzva-6pjs-k4xe-nw7d-qf credential valid until 2026-12-01T07:54:04Z (29d 23h) anchord conflux-ephemeral, with CAP_NET_ADMIN for its interface ephemeral in memory alone; /run/conflux-ephemeral holds the socket and the binaries, and goes with the run Reachable from any machine that runs: conflux up --taint brhk-2mq9-tzva-6pjs-k4xe-nw7d-qf Running in the foreground. Ctrl-C stops it and removes what it made; conflux status, from another terminal, reports it. With an installed conflux running too, conflux's pass-through reaches it with CONFLUX_EPHEMERAL=1.
You should see an
ephemeralrow. If you leave out--taint, the run mints a new taint, as the first machine of a network does.For a run without root, use proxy mode:
$ conflux proxy --ephemeral 8080=127.0.0.1:3000 --taint brhk-2mq9-tzva-6pjs-k4xe-nw7d-qf --no-ipv4
- While the run is up,
sudo conflux peerslists its peers. - After Ctrl-C,
sudo conflux statusshows noephemeral:block.
Running on an Issued Credential
To use a credential that a guardian issued, pass it with --manifest FILE. To read it from standard input instead, use --manifest - and pipe it in:
$ fetch-credential | conflux proxy --ephemeral --manifest - 8080=127.0.0.1:3000
Conflux never writes the credential to disk. The run takes these settings from it:
- The taints. Leave out --taint.
- The API the run renews against. If you also pass
--api, it must name the same host. - The IPv4 address, unless you pass
--ipv4or--no-ipv4.
You can use --manifest only with --ephemeral. To install a credential that the machine keeps, run sudo conflux enrol --manifest FILE. To send telemetry, pass --export HOST:PORT.
While It Runs
An ephemeral run behaves like this:
- It never prompts you. The IPv4 address comes from
--ipv4or--no-ipv4. If you pass neither, it comes from the credential, and if the credential has none, the run has no IPv4 address. - It renews in memory. When two thirds of the credential's lifetime have passed, the run renews it and passes the new chain to
anchorctl renew -cred -on standard input. If a renewal fails, it tries again every minute. - It ends with anchord. The run ends when anchord stops, or when its anchor stops inside anchord, for example because its credential runs out. Nothing restarts it, so start it from something that can, such as a container runtime or a CI job.
- It can observe. You can use
--observeand--export HOST:PORT, and both stop when the run ends. The inventory lasts as long as the run. Observing needs root. See Observing Traffic. - It keeps no core dumps. The run turns off core dumps for itself and its anchord, so the identity is never written to a file.
Each user can have one ephemeral run at a time. A run doesn't touch an installed conflux: it never reads, writes, stops or registers it. To run an ephemeral TUN anchor next to an installed one, first stop the installed anchor with sudo conflux down, because both need the overlay's routes.
Who Runs It
The account anchord runs as depends on who starts the run:
| Started as | up --ephemeral | proxy --ephemeral |
|---|---|---|
| root | conflux-ephemeral, with CAP_NET_ADMIN alone on Linux, and root on macOS and the BSDs | conflux-ephemeral, with no capability, and no_new_privs on Linux |
| an ordinary user | Needs root, to create the interface | That user, with no extra privileges |
| Administrator on Windows | That Administrator | That Administrator |
conflux-ephemeral (_conflux-ephemeral on macOS and OpenBSD) is a separate account from the installation's conflux account. Conflux creates it the first time a run started as root needs it, and conflux uninstall removes it. On Windows, an ephemeral run in either mode needs an elevated PowerShell.
Where It Keeps Its Socket
Each run uses one directory, its run root, which it creates when it starts and removes when it ends. The run root holds the run's lock, token and socket and the extracted anchor binaries, but never a credential:
| Started as | Run root |
|---|---|
| root on Linux | /run/conflux-ephemeral, or /var/lib/conflux-ephemeral where /run is mounted noexec |
| root on macOS and the BSDs | /var/run/conflux-ephemeral |
| an ordinary user | $XDG_RUNTIME_DIR/conflux-ephemeral, or /tmp/conflux-ephemeral-UID, then the user's cache directory |
| Windows | %ProgramData%\conflux-ephemeral |
CONFLUX_DIR set | $CONFLUX_DIR/ephemeral |
Reaching It from Another Terminal
conflux status shows a live run before the machine's own anchor. Until the run's anchor is up, it shows the run as starting.
Passed-through commands, such as conflux peers, reach the ephemeral anchor when it is the only one running. If an installed anchor is also running, they reach the installed one. To reach the ephemeral anchor instead, set CONFLUX_EPHEMERAL=1:
$ sudo CONFLUX_EPHEMERAL=1 conflux peers
conflux renew exits with code 69 during a run, because the run renews itself.
Stopping a Run
To stop a run, press Ctrl-C in its terminal, or send it SIGTERM. Anchord closes its anchor, and conflux removes the run root.
If conflux is killed instead, anchord stops with it on Linux, where it receives a parent-death signal, and on Windows, where conflux's job object ends it. On every platform, the next ephemeral run cleans up whatever a killed run left behind, and so does conflux uninstall. Until then, conflux status reports that a run left its run root behind.