Run one FutureOS agent on Linux, verify it locally, and connect remote terminal clients through a controlled TCP tunnel
FutureOS normally connects its CLI and terminal interface to the agent through local inter-process communication, so a default installation does not need a listening network port. For remote CLI or TUI access, FutureOS can instead expose an opt-in gRPC endpoint on a specific TCP address. This guide installs FutureOS on Linux, configures a model, starts and tests the agent, and then publishes the localhost-only gRPC endpoint through a Localtonet TCP tunnel. Keeping the service bound to 127.0.0.1 avoids opening it directly on every network interface.
📋 What's in this guide
How the FutureOS and Localtonet architecture works
FutureOS uses a single agent backend for interfaces such as its terminal UI, CLI, desktop application, mobile applications, and messaging integrations. The CLI and TUI are thin gRPC clients. On Linux, they connect to the local agent through per-user local IPC by default, using a Unix-domain socket rather than a TCP port.
That local-first default is important. Installing FutureOS and running future agent does not automatically create a network service that another computer can reach. For ordinary use on one Linux account, the default socket is the simplest option. If a TUI and agent run under the same account on the same server, there is usually no reason to enable TCP mode.
Remote CLI or TUI access changes the architecture. FutureOS provides an explicit --grpc-addr option that can make the agent listen on a TCP address. In this guide, the agent listens on 127.0.0.1:50051. The loopback address means the port is available only on the Linux host itself. We then configure a Localtonet TCP tunnel whose local target is that address and port.
The Localtonet client running on the Linux host establishes an outbound connection to one of our relay servers. The resulting tunnel provides a public host and port for the raw TCP connection. This does not require inbound router port forwarding, a public IP address, VPN setup, or an inbound firewall rule. The tunnel remains available only while the selected Localtonet client is connected and the tunnel is running.
127.0.0.1 prevents the gRPC port from listening directly on the server's LAN or public interfaces.
FutureOS also documents its own encrypted phone-to-desktop remote channel. That is a different workflow. A Localtonet TCP tunnel is most relevant when a remote FutureOS client needs to reach the opt-in gRPC service directly.
Prerequisites for self-hosting FutureOS on Linux
Prepare the host and access model before installing anything. You need a Linux machine on which you can run shell commands and install software for your user. The official installer supports Linux without requiring a source build. On Debian and Ubuntu, it installs the packaged desktop application and unified future CLI. On other Linux distributions, it uses a portable tarball.
The host also needs outbound internet access for the FutureOS installer, the model provider you choose, and the Localtonet client connection. If you install optional FutureOS skills from its catalog, that operation also needs network access.
Have the following ready:
- A supported Linux environment with a shell.
curl, because the documented installer command downloads the installation script with it.- A terminal in which you can run
future init,future config, andfuture agent. - At least one FutureOS model provider, either through FutureOS sign-in or a supported custom provider.
- A separate machine for the remote test if you intend to validate the public TCP path.
- A Localtonet account and a Localtonet client installed on the Linux device that runs FutureOS.
Model credentials are separate from Localtonet device authentication. A FutureOS provider key authorizes model use, while a Localtonet device token identifies the client device that operates the tunnel. Do not paste either credential into shell history, screenshots, public issue reports, or shared configuration examples.
FutureOS can expose tools for reading, writing, editing, and running shell commands. Its documentation describes configurable approval rules and sandbox tiers, and notes that availability and guarantees vary by platform. Select an appropriate approval or sandbox mode before processing untrusted prompts, repositories, files, or remote requests. Network tunneling controls reachability, but it does not replace FutureOS tool approvals or operating-system isolation.
Install FutureOS on the Linux server
FutureOS provides a one-line installer for macOS and Linux. On Linux, the script detects the platform and chooses the documented package format. No source compilation is required for this installation path.
Open a terminal as the intended FutureOS user
Use the same Linux account that will normally run the agent. FutureOS stores per-user configuration and runtime data, so switching accounts later can result in a different configuration or socket path.
Run the official Linux installer
Execute the documented installer command shown below. It downloads the installer from the official FutureOS distribution address and passes it to Bash.
Complete the initialization flow
The installer finishes by running future init. Follow its interactive prompts. If initialization is interrupted, run future init yourself after confirming that the command is installed.
curl -fsSL https://dl.future-os.cn/install.sh | bashPiping a remote script directly into a shell is convenient, but it also executes the downloaded content immediately. If your security policy requires reviewing installation scripts before execution, retrieve and inspect the official script through your normal software-review process rather than bypassing that policy. This guide does not recommend disabling endpoint controls or package verification.
After installation, check that the executable is available:
future init
Running initialization again is also a practical way to detect a missing executable or shell path problem. If the shell reports that future is not found, open a new terminal so updated environment settings can take effect, then retry. If it is still unavailable, review the installer output instead of guessing an installation path. The official installation method can differ between Debian or Ubuntu packages and the portable build used elsewhere.
Configure a model provider
A FutureOS agent needs at least one model provider before it can answer requests. Installing the executable alone is not enough. The preferred starting point is the interactive configuration command:
future configUse the prompts to select and configure an available model option. FutureOS supports its hosted model flow as well as bring-your-own-key and custom provider configurations. The best option depends on your provider, account, data-handling requirements, and model availability.
FutureOS hosted model sign-in
The documented device-flow sign-in command provisions keys and a model list:
future auth login
This command works whether or not the agent is already running. When the agent is running, the key can be applied live. When it is not running, the authentication information is written under ~/.future/agent/auth.json and is picked up when the agent starts.
Bring your own provider key
FutureOS also supports provider credentials in ~/.future/agent/auth.json. Most known providers have built-in base URLs and can discover their models. Some providers require a user-specific base URL. Custom OpenAI-compatible or Anthropic-compatible services can be described in ~/.future/agent/models.json.
Do not copy placeholder keys from examples into a live deployment. Avoid passing real API keys directly on a command line because they can be retained in shell history or exposed through process inspection. Restrict access to credential files using appropriate Linux ownership and file permissions.
| Configuration path | Best fit | Operational consideration |
|---|---|---|
future config |
Initial interactive setup | Guides the user through the available model configuration choices. |
future auth login |
FutureOS hosted models | Uses device-flow sign-in and provisions keys and a model list. |
~/.future/agent/auth.json |
Known providers and bring-your-own-key use | Contains sensitive provider authentication data and must be protected. |
~/.future/agent/models.json |
Custom compatible providers | Defines provider details and model metadata when they are not supplied by the built-in catalog. |
Optional skills
Skills are optional capability packs stored under ~/.future/agent/skills/. The agent can answer without installing them, so postpone this step until the basic model and agent are working. To inspect the catalog and install a specific skill, use:
future skills list
future skills install <name>
Running future skills install without a name installs every built-in skill. Installing only what the deployment needs is easier to review and maintain than enabling every optional workflow by default.
Start and verify FutureOS locally
Establish a working local baseline before adding TCP or Localtonet. This separates FutureOS installation and model problems from tunnel problems.
Start the agent with its default local transport
Run future agent in a terminal. It remains in the foreground and writes logs to standard output. Keep that terminal open during the test.
Launch the TUI as the same user
Open another terminal under the same Linux account and run future tui. By default, the client should use the per-user Unix-domain socket rather than TCP.
Send a harmless test request
Confirm that the TUI can create or open a session and receive a model response. Use a request that does not invoke shell or file tools while validating the initial configuration.
Stop the foreground agent
Return to the agent terminal and press Ctrl-C. The next section restarts it in explicit TCP mode.
future agentfuture tui
On Linux, FutureOS uses $XDG_RUNTIME_DIR/future/agent.sock when XDG_RUNTIME_DIR is set, otherwise it falls back to ~/.future/run/agent.sock. Unix clients can also honor FUTURE_AGENT_SOCKET. These details matter when the agent and client run under different users, when runtime directories disappear after logout, or when a stale environment variable points at the wrong socket.
The TUI and desktop application can start the agent automatically as a sidecar when no agent is running. For this tutorial, starting the agent explicitly is preferable because its log output remains visible and because we need control over the gRPC listening address.
Enable the opt-in FutureOS gRPC TCP endpoint
Stop any existing foreground agent, then start FutureOS with the documented loopback TCP address:
future agent --grpc-addr 127.0.0.1:50051
The address has two parts. 127.0.0.1 restricts the listener to the local machine, and 50051 is the port used in the documented FutureOS TCP example. Keep this agent terminal running.
In another terminal on the same Linux host, explicitly direct the TUI to the TCP endpoint:
FUTURE_AGENT_GRPC_ADDR=127.0.0.1:50051 future tuiTest a simple request again. A successful response demonstrates that the client can reach the agent through gRPC over TCP, independent of the normal Unix-domain socket path. This local TCP verification is the most important checkpoint before creating the tunnel.
0.0.0.0 just to make tunneling work
The Localtonet client runs on the same Linux device and can target 127.0.0.1:50051 directly. Binding FutureOS to every interface can expose the gRPC service to other systems on the LAN or to the internet if separate routing or firewall rules permit it. A broader bind is unnecessary for this workflow.
Create a Localtonet TCP tunnel for FutureOS
Once the local TCP test succeeds, configure Localtonet on the Linux host. A TCP tunnel is appropriate because the FutureOS client is speaking gRPC over a raw TCP connection. An HTTP tunnel is not the right choice for this documented endpoint, and standard tunneling should not be described as a VPN.
Current client installation details, available relay servers, and account options can change by platform, client version, region, or plan. Obtain the current Localtonet client and the available server selection from our dashboard and Localtonet documentation. Do not copy a device token or server code from somebody else's example.
Install and run the Localtonet client
Install the current Localtonet application for the Linux host and keep it running on the same device that can reach 127.0.0.1:50051.
Authenticate or select the Linux device
Use the device-specific authentication token associated with this client. Treat the token as a secret. Never place it in tutorial commands, repositories, logs, or screenshots.
Select an available relay server
Choose from the relay servers currently presented by our platform. Available values must come from the current dashboard rather than a hardcoded example.
Create the TCP configuration
Select the TCP tunnel type and set the local target IP address to 127.0.0.1 and the local target port to 50051. This points the tunnel at the verified FutureOS gRPC listener.
Start the tunnel and record its endpoint
Creating a tunnel does not start it. Use the Start button, then record the assigned public host and port. The tunnel is available only while the selected Localtonet client remains connected and the tunnel is running.
Do not substitute the public endpoint into the FutureOS server command. The agent should continue listening on 127.0.0.1:50051. The public host and port belong on the remote client's side of the connection.
Connect a remote FutureOS CLI or TUI client
Install FutureOS on the remote Linux or macOS client using its supported installation process. The remote machine needs the future command, but it should not start a separate local agent for this test. Instead, set FUTURE_AGENT_GRPC_ADDR to the public host and port assigned by the running Localtonet TCP tunnel.
FUTURE_AGENT_GRPC_ADDR=PUBLIC_HOST:PUBLIC_PORT future tui
Replace PUBLIC_HOST and PUBLIC_PORT with the exact values shown for your tunnel. Do not include http:// or https:// unless FutureOS documentation for a future client version explicitly requires a URI. The documented variable takes a host-and-port address, and the Localtonet tunnel is forwarding raw TCP.
Set the environment variable for one command during initial testing rather than exporting it globally. This prevents unrelated FutureOS sessions from unexpectedly connecting to the remote agent. If the TUI starts and displays the expected server-side sessions, send a low-risk prompt and watch the agent logs on the Linux server.
A successful end-to-end test confirms all of the following:
- The FutureOS agent is running with TCP mode enabled.
- The gRPC listener is reachable locally at
127.0.0.1:50051. - The Localtonet client can reach that loopback target.
- The selected tunnel is started and its device is connected.
- The remote client is using the assigned public host and port.
- The FutureOS client and agent can complete their gRPC exchange through the TCP tunnel.
Stop the remote TUI after testing. When remote access is no longer needed, stop the tunnel in our dashboard. You can later start it again when required or delete it if the configuration is no longer useful. Also stop the foreground FutureOS agent with Ctrl-C if the server should no longer accept agent requests.
Security and operational guidance
A working network path is not the same as a complete authorization policy. The supplied FutureOS evidence establishes how to enable and address the gRPC endpoint, but it does not establish an independent authentication mechanism for arbitrary public gRPC clients on that endpoint. Do not assume that enabling TCP automatically adds user authentication, per-client authorization, or transport encryption.
A client reaching the FutureOS agent may interact with sessions and agent capabilities. Keep the tunnel stopped when it is not needed, share the endpoint only with intended operators, apply the access controls available in your current Localtonet account, and retain restrictive FutureOS approval and sandbox settings. Confirm the security behavior of the FutureOS version you deploy before allowing untrusted users or networks to connect.
Use least-privilege agent capabilities
Review which directories and tools the FutureOS agent can use. A remote operator should not automatically gain unrestricted access to the host simply because remote access is convenient. Use Manual or Sandboxed operation where appropriate, particularly when working with untrusted content. Platform-specific sandbox behavior differs, so test the exact Linux environment rather than relying on assumptions from another operating system.
Protect both categories of credentials
FutureOS provider keys and Localtonet device tokens serve different purposes, but both are sensitive. Keep provider files under the intended Linux user's home directory and restrict their permissions. Keep the Localtonet token in the supported client configuration rather than adding it to scripts. Redact tokens, model keys, public endpoints, session content, and agent logs before requesting help.
Use explicit lifecycle controls
Start the FutureOS TCP listener only when required. Start the Localtonet tunnel only when remote connectivity is required. Creating a Localtonet tunnel does not make it run automatically, and stopping the tunnel removes the public path without requiring you to reconfigure FutureOS. This separation is useful for short maintenance sessions.
Do not confuse tunneling with FutureOS application security
Localtonet provides the connectivity path from a public host and port to the local service. FutureOS remains responsible for its application behavior, model access, tool approvals, sessions, and sandbox controls. The Linux administrator remains responsible for host hardening, updates, account security, process supervision, and credential storage.
Troubleshooting FutureOS and the TCP tunnel
The future command is not found
Open a new terminal and run future init again. Review the installer output for errors and confirm that the installation completed. Do not guess a binary location because the official installer uses different packaging paths depending on the Linux distribution.
The agent starts, but it cannot answer
Run future config and confirm that at least one model provider is configured. If using the hosted model flow, complete future auth login. If using your own provider, verify that the authentication file belongs to the same Linux account running the agent and that its key and provider details are valid.
The local TUI cannot reach the default agent
Confirm that the agent and TUI run as the same user. Check whether FUTURE_AGENT_SOCKET is set to an obsolete path. On Linux, the normal socket is under $XDG_RUNTIME_DIR/future/agent.sock when that variable is set, otherwise under ~/.future/run/agent.sock.
The local TCP test fails
Verify that the agent was started with exactly the intended address:
future agent --grpc-addr 127.0.0.1:50051Keep that process running, then test from a second terminal:
FUTURE_AGENT_GRPC_ADDR=127.0.0.1:50051 future tuiResolve this failure before investigating Localtonet. A tunnel cannot repair a service that is not listening or a client that cannot communicate with the local endpoint.
The local TCP test works, but the public endpoint does not
Check the Localtonet side in order. Confirm that the Linux device is connected, that the tunnel is configured as TCP, that its local target is 127.0.0.1:50051, and that the tunnel has been started. Then copy the currently assigned public host and port again. Do not use a web browser as the primary test because this is a gRPC TCP endpoint, not a normal website.
The remote client starts a local agent instead
Ensure that FUTURE_AGENT_GRPC_ADDR is set in the same shell invocation that launches the remote TUI. Use the one-command form shown in this guide. Check for spelling errors, an omitted port, or an accidental URL scheme.
The connection worked and then stopped
Verify all three long-running components: the FutureOS agent process, the Localtonet client, and the tunnel itself. The public endpoint works only while the selected Localtonet device is connected and the tunnel is running. A server reboot, user logout, terminated foreground shell, or stopped tunnel can interrupt the path.
The remote TUI connects to the wrong FutureOS instance
Inspect the remote shell's FUTURE_AGENT_GRPC_ADDR value and the public endpoint selected in our dashboard. FutureOS also supports agents started with a separate home directory, and those instances have distinct state. Avoid persisting a global environment variable until you have confirmed which agent it addresses.
Frequently asked questions
Does FutureOS open a TCP port by default?
No. On Linux and macOS, FutureOS clients use a per-user Unix-domain socket by default. TCP mode is opt-in and can be enabled by starting the agent with a gRPC address such as future agent --grpc-addr 127.0.0.1:50051.
Why should the FutureOS agent listen on 127.0.0.1?
The loopback address limits direct access to processes on the same host. The Localtonet client can still forward that local endpoint, so binding FutureOS to every network interface is unnecessary for this workflow.
Should I use an HTTP or TCP tunnel for the FutureOS gRPC endpoint?
Use a TCP tunnel for the documented --grpc-addr endpoint. The remote FutureOS client expects a host and port for its gRPC connection, and the tunnel forwards that raw TCP traffic to the local listener.
Do I need router port forwarding or a public IP address?
No. The Localtonet client establishes an outbound connection to our relay server. You do not need inbound router port forwarding, a public IP address, a VPN, or an inbound firewall change for the documented tunnel workflow.
Is creating a Localtonet tunnel enough to make it available?
No. After creating the tunnel, start it with the Start button. It remains available only while the selected Localtonet client is connected and the tunnel is running.
Does the tunnel replace FutureOS approvals and sandboxing?
No. The tunnel provides connectivity. FutureOS approval rules, sandbox selection, model authorization, and tool permissions remain separate controls and should be configured according to the risk of the tasks and content being processed.
Is Localtonet required for FutureOS mobile access?
Not necessarily. FutureOS documents its own encrypted phone-to-desktop remote channel. The workflow in this guide is specifically useful for remote CLI or TUI clients that need to connect to the opt-in gRPC TCP endpoint.
Can I run FutureOS headlessly on a Linux server?
FutureOS documents a headless backend for server use and also supports starting the agent directly from a terminal. This guide uses the documented future agent command because it exposes logs and allows the gRPC address to be selected explicitly.
Connect your self-hosted FutureOS agent with Localtonet
After FutureOS is installed, configured, and verified locally on 127.0.0.1:50051, create a Localtonet TCP tunnel to give an authorized remote CLI or TUI client a public host and port without opening an inbound router port.
