GrigDesk architecture

The application is where you manage work. The server is where tasks run. A relay helps connect devices when a direct connection is unavailable.

Everything on one computer

The application and server run together on your Linux computer.

Your computer

ApplicationTasks, chats and acceptance

Local

GrigDesk serverCode, agents and execution

Connect directly to a remote server

The server has an internet-accessible address and accepts application connections.

Your computerApplicationYou assign tasks and accept results

Direct

Remote Linux machineGrigDesk serverProjects are stored and agents run here

Take your home project with you

A relay on a VPS connects your phone to a home PC that cannot be reached from the internet.

Phone or tabletApplicationYou manage the work

Internet

Internet VPSRelayForwards encrypted traffic

From home

Home PCGrigDesk serverCode, agents and execution

The home server opens the connection to the relay. At home, the application connects directly to the same server.

Work stays on your computerYou manage work in the application; agents run tasks on the same PC. No relay is needed.

Tasks run on the remote machineThe desktop connects without a relay. Your computer does not need a local server.

Tasks still run at homeThe VPS only needs the relay. Your project and AI tools stay on the home PC.

Three components

Server

The server manages chats and pipelines, starts AI runners and stores history and results. It runs on a Linux machine containing your repositories, tools and project environment. This can be a home PC or a remote server.

It can run as a background service. Tasks can continue while the application is closed, provided the machine and server remain running.

Application

Use the desktop application or Android application to create tasks, chat with agents and make decisions. Project code and tools stay on the server machine.

The application can be installed and opened separately. The Machines screen stores connections to servers. Connecting to a remote machine does not require a local GrigDesk server.

For local work, the desktop reuses an existing server or starts its own. It can also connect directly to an accessible remote server without a relay.

Relay

A relay on an internet-accessible VPS can connect the mobile application to a home PC behind NAT. It forwards encrypted traffic between the device and GrigDesk server. It does not run agents or receive chat content in plain text. Repositories and development tools stay on the server.

Deployment options

Everything on one computer

Install GrigDesk on a Linux computer and open the application. If no server is running, the application starts its own and stops that server when the window closes.

Direct connection to a remote server

1. Install the GrigDesk server, repositories, AI CLIs and project dependencies on the remote Linux machine.
2. Enable the application listener and make the chosen address and port reachable.
3. Obtain the pairing string or QR code under Access → Devices or through the CLI.
4. Add the machine to the desktop application and connect.

Agents work on the remote machine. See the device pairing guide for details.

Keep the server running without the window

Start the server service before opening the application. The window reuses it and leaves it running when closed. Closing a local application also leaves a remote server running.

Home PC with a relay on a VPS

1. Run the GrigDesk server as a service on the home Linux computer.
2. Install the relay on a separate VPS.
3. Add its address in the phone application settings in GrigDesk and obtain the relay configuration.
4. Pair the Android application using the QR code.

The home PC must remain on, with its server and relay connection running. The VPS provides connectivity; tasks still run at home. The full Android application also supports direct connections to reachable machines.

Read the mobile architecture, relay deployment and unified application guides for details.

Continue with installation or your first project.