Feature Request: Remote Project Support via SSH (Willing to Contribute)

[Jerry-Terrasse]

Background & Motivation

Claude Code UI is a great project! 👍 It already provides a unified interface for projects, sessions, file browsing, terminal, and chat on both desktop and mobile. But right now, everything is limited to using the Claude instance running on the same machine where Claude Code UI is installed. In practice, many of us develop on remote servers (dev boxes, CI machines, etc.), and it would be much more convenient if those projects could also be opened and managed directly inside Claude Code UI. That way, we wouldn’t need to install separate instances of the app on every server and then juggle between them.

Feasibility

I’ve done some basic testing and confirmed that connecting via node-ssh and running Claude remotely works. From what I can see, this approach would integrate naturally with the current UI without breaking local workflows.

Compatibility Design

• Remote project option: when creating a project, users could choose “Remote project”, provide host information, and Claude Code UI would maintain that configuration. From the user’s perspective, it should look and behave like any other local project.

• Consistent UI & API: core actions (project browsing, chat, terminal, file editing, Git operations) should work the same, with only the backend executing commands remotely.

Discussion about Remote Calls

One open question is how to properly implement the invoke method of remote commands.

• A straightforward option is to map operations directly into SSH commands, though efficiency may be limited.

• Another idea, inspired by vscode-server, is to provide a lightweight remote daemon for more efficient execution.

I’m open to discussing other approaches that might fit better.

Willing to Contribute

I’d be happy to help implement this feature and contribute PRs. I’m open to adjusting the design based on maintainer feedback, and will work with you through reviews and testing to make this more practical and useful. 🤝

[viper151]

@Jerry-Terrasse that's a very good idea. How would both options though be different from just running claude code ui remotely and installing it on the dev server?

[Jerry-Terrasse]

@viper151 Thanks for the reply! I’d like to emphasize why this proposal is necessary:

• Unified management: Projects are often spread across many different hosts. With remote support, it becomes possible to access projects on multiple hosts from a single UI page, instead of installing and configuring ClaudeCodeUI on each host separately.
• Security restrictions: Some hosts cannot run a web service directly due to security policies. Running the UI on a single host that can expose a web service, while connecting to other hosts remotely, solves this issue.

This would improve usability in multi-host and restricted environments.

[viper151]

@Jerry-Terrasse that makes sense. The daemon makes more sense even though I'm not sure of the exact architecture you are thinking of. When it comes to UI I would add it as an option when you try to create/add a project and show an indicator on the project list. I would also save the connection in the database instead of saving locally. Would you use Claude code locally or on the remote server ?

I hope that makes sense

[Jerry-Terrasse]

Thanks for your reply! I’m glad we’re aligned on the overall idea, and I fully agree with your suggestions about using a daemon, adding a remote project option in the UI, and storing connection info in the database.

Regarding your question on whether Claude Code should run locally or remotely:
I believe that when working on a remote project, Claude Code itself should run on the remote host. This has several advantages:

1. Consistency – Remote Claude works on remote projects just like local Claude works on local projects; everything happens in the “native” environment.
2. Clean separation – With a proper remote call mechanism, the UI and Claude remain decoupled. That way, all we really need is to execute Claude commands remotely and capture stdout, instead of building complex “remote editing” logic inside Claude itself.
3. MCP compatibility – Many MCP tools depend on the host environment. If Claude runs locally, each tool would need to be specially adapted for remote access — which would be difficult to maintain on a per-tool basis and likely impractical in the long run.

As for the daemon architecture, I have some suggestions I’d like to discuss:

• Deployment: The UI checks if ccud exists on the remote host. If not, it uploads and deploys it (e.g. ~/.ccud/servers/v1.0.0/bin/ccud) and then starts it. The UI also handles lifecycle and auto-updates.
• Communication: The UI launches ccud via SSH, using stdio + JSON-RPC for efficient two-way streaming communication.
• Remote features supported by ccud:
  1. Command execution – Git operations and invoking Claude remotely.
  2. File system – read/write, list directories, move/delete, file watching.
  3. Terminal/processes – remote Shell/PTY with optional tmux session persistence.
  4. System info – host environment details, resource usage, heartbeat/health checks.

flowchart LR
  subgraph Local["Local Host"]
    UI["Claude Code UI"]
  end

  subgraph Remote["Remote Host"]
    CCUD["ccud daemon"]
    FS["File System"]
    TERM["Terminal / PTY"]
    CMD["Command Exec (Git, Claude)"]
    SYS["System Info"]
    CCUD --> FS
    CCUD --> TERM
    CCUD --> CMD
    CCUD --> SYS
  end

  %% 双向通信
  UI <-->|"SSH (stdio + JSON-RPC, bidirectional)"| CCUD

  %% 推送部署
  UI -->|"deploy / update ccud"| CCUD

If this direction makes sense to you, I’d be happy to contribute PRs or collaborate on dividing up the work to make this feature happen.

[viper151]

That makes sense indeed. Feel free to start working on the PR. Looks interesting. I wouldn't go as far as doing system info. Moreover there is a new integration that was added recently for taskmaster. We should either do this through ssh or hide it if we do not. What would the security layer be around the daemon ( given it has access to the files?)

[Jerry-Terrasse]

OK, I’ll start working on this soon and open a PR once the first basic functionality is ready. However, I’m currently busy with other tasks, so I may not have much time to devote to this — hope that’s understandable.

I’ll follow your advice not to include system info and also take Taskmaster into consideration. As for the daemon’s security layer, I don’t have concrete ideas at the moment. From my understanding, when Claude Code UI runs locally, there isn’t a specific security/auth mechanism either — it simply has access to whatever files the running user is permitted to access. Similarly, ccud would only be able to access files that the corresponding user account has permissions for.

By the way, is there any instant messaging channel (e.g. Telegram, Discord, Slack, or Matrix) that you prefer for quicker discussions?
If not, that’s totally fine — we can keep everything here on GitHub.