Plain Portal

Remote Portal Session

Open an encrypted tunnel to a remote machine and run Python code on it.

1. Start the remote side and connect

The remote side must be running first. Either start it yourself (if you have access to the platform CLI) or ask the user to start it:

start requires either --read-only or --read-write. Always use --read-only unless the user has explicitly asked for database writes.

Both start and connect are long-running foreground processes. If you run start yourself, use run_in_background so you don't block. Once it prints a portal code (e.g. 7-crossword-pineapple), read the code from the output. If the user ran it, ask them for the code.

Then connect (also use run_in_background):

uv run plain portal connect <code>

2. Run commands

Execute Python code on the remote machine:

uv run plain portal exec "<code>"

Output streams line by line in real time. The last expression's value is returned (like a REPL).

For long-running commands, increase the timeout (default 120s):

uv run plain portal exec --timeout 300 "<code>"

For machine-readable output:

uv run plain portal exec --json "<expression>"

File transfer

uv run plain portal pull <remote_path> <local_path>
uv run plain portal push <local_path> <remote_path>

Push is restricted to /tmp/ on the remote machine.

3. Disconnect

Kill the connect process to end the session. This also frees the remote process.

Important

• Use --read-only sessions. Database writes will fail unless the remote was started with --read-write --yes, which should only happen at the user's explicit request.
• Each exec gets a fresh namespace. Variables don't carry between commands. Put setup and queries in one code block if they depend on each other.
• Use plain portal exec for quick queries. For heavy data export, write to /tmp/ on the remote and pull the file.
• If the session drops, the remote side must be restarted and a new code used to reconnect.