--host mode runs remote pulam as SSH user, fails when kaval socket is owned by a different user

[ic4-y]

When using pulam-tui --host nixops@kolu-server, the remote pulam runs as the SSH user (nixops, UID 1000). If kaval runs as a different user (kolu, UID 998) with its socket directory at 0700, the remote pulam gets `EACCES` trying to connect:

pulam: could not reach kaval at /tmp/kaval-7681-998/pty-host.sock (connect EACCES)

This happens because:

1. `--host` mode SSHes as the specified user and runs pulam as that user
2. Kaval enforces `0700` on its socket directory (security: PTY socket grants full terminal control)
3. The SSH user can't access a `0700` directory owned by a different user

Use case: kolu-server runs kaval as a dedicated service user (kolu). Developers SSH in as nixops. `--host` mode should work without requiring SSH as the kaval owner.

Proposed solutions:

• Add a `--user ` flag to run the remote pulam via `sudo -u `
• Or auto-detect the kaval socket owner and use `sudo` implicitly
• Or add a `--sudo` flag to wrap the remote pulam command in `sudo -u `

Environment:

• kolu version: 1.1.0
• Kaval socket: `/tmp/kaval-7681-998/pty-host.sock` (owned by kolu:kolu, 0700)
• SSH user: nixops (UID 1000, in kolu group)

[srid]

What's the X here?

[ic4-y]

What's missing in the first sentence?

I have two machines, one running kolu + kaval + pulam as a service. I want to connect to that via remote with pulam-tui. And that doesn't work because of the problem that is described.

Afaik the problem is that the remote ssh user can't access the socket because that is owned by whatever user runs kaval. And these don't match.

My little model was thinking that Kaval socket being accessible only by Kaval user instead of a group is by design.

Should they match? Is that intended by design that pulam-tui on remote via ssh is run by whoever runs pulam on the machine?

[srid]

I mean, why (X) even try to access another user's kaval (Y)?

[ic4-y]

The kolu/kaval/pulam host is not a personal machine to me. It's a deployment. It doesn't have my personal user account. And it doesn't run kolu under my personal user account eitjher. kolu runs under an account named for that service, aptly named kolu ... and like any other service, if I need to access something specific to that service, I'd have a group kolu which then allows users that are in that group to access the resource.

So I was thinking that should work here as well. But it doesn't, because kaval likes to be very specific.

So group permissions for the socket would solve this I believe. But if I am not mistaken, kaval doesn't like this right now.

Generally speaking: all this brings me back to a question I had at the very beginning when looking into this: why do this over ssh at all? Why not have a token authenticated API of some kind?

...

I guess there are a couple of possible solutions:

• make the user that owns the kaval socket a user you can ssh into the machine with
• allow kaval to share the socket with others via group permissions

[srid]

(responded below)

[srid]

A bit of grounding on why the group-permissions idea is blocked, then a few questions to figure out if there's a general need here.

Why the socket is owner-only (and group-sharing won't work)

The kaval socket isn't a read-only feed — it serves the full pty-host surface: write / kill / spawn / getScreenText. Anyone who can connect() to it gets total control of every terminal on the box. So the owner-only directory is the entire auth model — there's no token layer because the filesystem permission is the auth.

That's enforced at the moment kaval serves. The gate (unix-socket.ts) is:

st.isDirectory() && st.uid === getuid() && (st.mode & 0o077) === 0

(mode & 0o077) === 0 rejects any group or other bit — so 0750 (group-read) fails too, not just world-readable. If the socket dir has group access, kaval doesn't share the socket — it refuses to serve at all. So group-sharing isn't an unimplemented feature; it actively trips a security invariant by design. The threat it guards against is exactly a shared multi-user host.

The intended remote path

pulam-tui --host <ssh> runs ssh <host> pulam --stdio, so the remote pulam runs as whoever you SSH in as, and that's the identity dialing kaval. The design assumes the SSH user and the kaval owner are the same identity. In your setup they aren't (kolu owns kaval, you log in as nixops), which is where the EACCES comes from.

The path that needs zero new code: SSH in as the kolu service user (e.g. a restricted/forced-command key for it). Then you are the owner and the socket just works.

Questions, to see if there's a general need

1. Why can't you SSH in as the kolu user directly? A restricted key for the service account would solve this with no Kolu changes — is there something that rules that out?
2. Is this a problem you expect others to hit, or a property of how this one box is set up (service runs as kolu, you log in as nixops)? If the fix is "align those two users," that's deployment config rather than a Kolu feature.
3. Do you actually need full PTY control remotely, or just the awareness view? If it's only the status board you're after, reaching the full-control socket is the wrong tool — and that reframes the request entirely.

We keep a high bar for adding feature surface, so I'd like to land on whether this is a docs/setup answer or a genuinely general gap before proposing anything.

[ic4-y]

The design assumes the SSH user and the kaval owner are the same identity.

That is the problem.

My deployment doesn't assume that the kaval owner is among ssh users. I think I will just change that and ssh into the machine with that user.

I think it would be a good idea to document that assumption explicitly somewhere, if this isn't the case already.

[srid]

Glad SSHing in as the kaval user sorts it on your end — that's the design's intended path.

And good call on documenting the assumption: done in #1623. It now says, in three places, that --host runs the remote daemon as the SSH user (so that user must be the kaval owner):

• the --host help text for both kaval-tui and pulam-tui, and
• the remote-terminals Atlas note — with a callout explaining why the socket is owner-only (it grants full PTY control, so the 0700 dir is the auth boundary; there's no group-share knob by design).

Thanks for the report and the back-and-forth — it turned into a real doc gap worth closing. Closing this out.