This release is a pre-release and may not be stable for production use.
Portacode
Build it. Own it. Take it anywhere.
Portacode is an AI-powered builder and mobile-first development environment that works on real Linux machines. Describe what you want to build, let Portacode work through the implementation on a machine you control, and keep the result as ordinary source code, data, containers, and configuration.
It combines an AI coding agent with the tools developers expect from a real machine: a terminal, files, Git, diffs, processes, and deploys. Use hardware you already have, connect a VPS or homelab, deploy to supported infrastructure, and move the project when your needs change.
Get started · Open Portacode · Android app · Report an issue
Why Portacode
- You own the result. Projects remain ordinary files on an ordinary machine, not artifacts trapped in a proprietary runtime.
- Real tools, not a preview sandbox. Work with a real terminal, filesystem, Git repository, services, containers, databases, and deploys.
- Your infrastructure is a choice. Connect an existing machine, use managed capacity, or run projects on your own supported infrastructure.
- Leaving is supported. Back up, transfer, or move a project instead of rebuilding it around a platform-specific format.
- AI changes stay reviewable. Inspect diffs and project state while the agent works, and decide what it is allowed to change.
- Built for mobile as well as desktop. Browse a project, review changes, use a terminal, and respond to work without waiting to get back to a desk.
- No approved-stack list. If your language, framework, database, or tool runs on the underlying Linux machine, it can be part of your project.
What You Can Do
Portacode supports more than remote terminal access. From the same browser-based workspace you can:
- ask an AI agent to create, change, debug, and deploy software;
- inspect files, branches, Git status, and line-by-line diffs;
- work directly in persistent terminal sessions;
- connect and switch between your own machines;
- provision clean environments from reusable deployment templates;
- run repeatable build, test, deployment, and runbook workflows from YAML;
- expose services through HTTPS and custom domains on supported infrastructure;
- manage projects from a phone, tablet, or desktop.
The product evolves quickly. The live Portacode website and technical guides are the source of truth for currently available integrations, templates, limits, and infrastructure options.
Start Building
You do not need to prepare a machine before trying Portacode. Start at portacode.com, describe the outcome you want, and choose where the project should run.
To bring an existing machine into Portacode, pair it once using the dashboard and the CLI below.
Connect Your Own Machine
Portacode's Python package is the device-side CLI and agent. It connects an existing Linux/Python-capable machine to your Portacode account so the web workspace can work with its projects and developer tools.
Recommended Linux setup
- Sign in to Portacode and select Pair Device.
- Run the activation command shown there on the target machine. It installs Portacode in a dedicated virtual environment, pairs the device, and configures its persistent service.
- Approve the pairing request in the dashboard.
The command has this form; use the short-lived code displayed in your own dashboard:
curl -fsSL https://portacode.com/static/activate_portacode.sh \
| bash -s -- --pairing-code YOUR_CODE
Review the downloaded script before running it if that is required by your environment. See the pairing guide for supported distributions, a fully manual installation, and Proxmox-specific setup.
Manual CLI setup
If you already have a suitable Python environment:
python -m pip install --upgrade portacode
portacode connect --pairing-code YOUR_CODE \
--device-name "My Linux Device" \
--project-path /absolute/path/to/project
Approve the request in the dashboard. The device stores its identity locally and reuses it for later connections. For an always-on connection, install the supervised service after pairing:
portacode service install
portacode service status
System-wide service installation may require elevated privileges. Run portacode --help, portacode connect --help, or portacode service --help for the options supported by the installed version.
Automation and Deployments
A portafile.yaml can describe a repeatable workflow for a new disposable environment or an existing device. Depending on the workflow, it can select a base environment, request resources, create project paths, collect inputs, run ordered build/test/deploy steps, expose services, and define success or failure behavior.
This keeps automation portable and reviewable alongside the project while Portacode handles orchestration and status reporting. The schema is intentionally documented on the live site because it gains capabilities more frequently than the CLI README changes.
See the CI/CD and portafile.yaml reference or browse one-click deployment templates.
Your Infrastructure
Existing Linux machines can be paired directly. For self-hosted provisioning, a supported Proxmox node can become Portacode infrastructure, allowing projects and automation to create isolated environments against the capacity you control. Services can be connected to custom domains through the supported Cloudflare Tunnel flow.
Security and Control
Each paired device has its own cryptographic identity. The private key is stored on the device, connections are encrypted in transit, and access can be revoked from Portacode. Pairing codes are short-lived and a new device still requires approval in the dashboard.
AI work is designed around visible project state and reviewable diffs. As with any remote administration or coding-agent tool, connect only machines and project paths you intend Portacode to access, review proposed changes, and use appropriate operating-system permissions and backups.
Identity Storage and Containers
The CLI uses the operating system's application-data directory (through platformdirs) and stores its device identity under portacode/keys/. Typical locations are:
- Linux:
~/.local/share/portacode/keys/ - macOS:
~/Library/Application Support/portacode/keys/ - Windows:
%APPDATA%\portacode\keys\
When running the CLI in a container, persist the relevant application-data directory so the container retains its device identity across rebuilds. The examples demonstrate the pattern:
examples/simple_device— one container with a persistent workspace and identityexamples/workshop_fleet— a multi-seat lab with separate persistent workspaces
Guides
- Pair an existing device
- CI/CD and
portafile.yaml - One-click deployment templates
- Self-host on Proxmox
- Connect a custom domain
- Current usage limits
Contributing and Support
Bug reports, focused fixes, and documentation improvements are welcome. Open an issue or a pull request in this repository.
For product support, email support@portacode.com.
License
Portacode's public device-side client is available under the MIT License.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file portacode-1.5.28.dev0.tar.gz.
File metadata
- Download URL: portacode-1.5.28.dev0.tar.gz
- Upload date:
- Size: 747.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.11.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f0d3ad39cb3998f8b127aa8d4cf1cb9a1aac80a7ca0bf97b86699e5e84854d20
|
|
| MD5 |
2bf18f8bc95e3ffc45cd63b01f4f273b
|
|
| BLAKE2b-256 |
3ac8abbeab257fa03e9622f8a36231bed6d89fdd8a43ed0afe0a011ad0168621
|
File details
Details for the file portacode-1.5.28.dev0-py3-none-any.whl.
File metadata
- Download URL: portacode-1.5.28.dev0-py3-none-any.whl
- Upload date:
- Size: 441.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.11.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8a6f9e93bd06787d4187b7827db4bbe0a63ca8f435858baf06fdaa05cddd8125
|
|
| MD5 |
2050d7a6789d4908a3222865a8a50e78
|
|
| BLAKE2b-256 |
25f0207a491a0d6df78fc36c4b5f2d423bd79a27cf3df61d36f60d35fa9ec3b3
|
