Deploy Your Phoenix Workspace to a Remote Server Using Railgun

Source: Dev.to

Prerequisites

• Completed Phoenix Workspace
• Validated deployment bundle
• Remote Linux server (Ubuntu recommended) with SSH access
• Phoenix installed locally

MatrixOS requires no Docker, Kubernetes, or other container orchestrators. Railgun provisions everything it needs.

Configure SSH Target in Phoenix

1. In the top bar, go to Registry → SSH Targets.

2. Add a new SSH entry:

   Field	Value
   Host	your server’s IP
   Port	22 (default)
   Username	your Linux user
   Authentication	password or private key
   Install Path	directory where MatrixOS will live (default: /matrix)

3. Save the profile. Phoenix will reference this profile during deployment.

Create a Deployment Bundle

The bundle includes:

• Full agent tree
• Cryptographic identities, certificates, and signatures
• Constraints, configuration, encrypted directive
• Swarm AES keys

If you haven’t created a bundle yet:

1. Open the Workspace.
2. Click Deploy.
3. Provide a label.
4. (Optional) Enable Clown‑Car mode to embed agent source.
5. Choose Railgun‑enabled deployment.
6. Click Build.

Your deployment is now ready to be installed on a server.

Upload Your Deployment Bundle Using Railgun

1. From the top bar, open Deploy → Railgun Deploy.

2. Select:

   • Your SSH target (created above)
   • The deployment bundle (auto‑selected by Phoenix)
   • The universe name
   • Any optional flags (e.g., --verbose, --debug, --clean)

3. Click Deploy.

What Happens Under the Hood

• A secure SSH session is opened.

• The bundle is uploaded via SFTP to:

  /matrix/boot_directives/.json

• Railgun injects the swarm key in‑memory (never written to disk).

• A boot command is assembled and executed on the remote host:

  matrixd boot --universe  --directive /matrix/boot_directives/ 

• Phoenix streams the live remote output back into the dialog window, providing real‑time visibility of the swarm coming online.

Streamed Output Includes

• Directive validation
• Identity verification
• Swarm key handshake
• Matrix root agent boot sequence
• Child agent spawning
• Agent tree distribution
• RPC router initialization

The output is captured via RailgunWorker.sig_stdout and RailgunWorker.sig_stderr, giving you the same visibility as an interactive SSH session.

Post‑Deployment Operations

When the Railgun dialog reports:

[RAILGUN] Deploy finished (exit=0)

you can begin operating the running swarm:

1. Connect → Select Deployment.
2. Phoenix uses the deployment’s metadata to establish a WebSocket handshake with the server’s matrix_websocket agent.

Once connected you’ll see:

• Live updating Agent Tree
• Real‑time configuration inspectors
• Log streaming
• Tools for restart, hotswap, and injection

Operational Management

With the swarm active, Phoenix can:

• Restart, delete, or inject agents/subtrees
• Push live configuration changes
• Hotswap Python source code
• Route RPC calls
• Monitor heartbeats
• Display spawn history and constraint violations
• Validate runtime agent trees

Your distributed system is now:

• Cryptographically signed
• Fully encrypted
• Identity‑isolated
• Operationally visible in Phoenix
• Controllable at runtime

Resources

• MatrixOS GitHub:
• Phoenix GitHub:
• Discord:
• YouTube tutorials:
• X / Twitter: