Can't open projects from Shared Ghidra Server via Headless API

[j4s0n]

I am trying to use the headless Docker container with a remote Ghidra server. The /server APIs allow me to authenticate, view repos, view files in a repo, and check out files from the repo. However, I can't figure out a way to open a file once it has been checked out. I can see the files exist in the headless container's ghidra-data share. I've tried getting the /open_program, /open_project, and /load_program_from_project to no avail.

I noticed the notes in Issue #33 mention an initial intention to add a POST /program/open-shared for this method, but it doesn't look like that was ever done. I think Issue #46 was related to a similar issue, but the OP never responded.

Any advice on how to accomplish this?

[t0xk]

Has now been fixed with recent PR merges

[j4s0n]

Thanks, PR#121 does help improve the headless workflow, but I still don't see a way for it open projects from a server. The /server/ API endpoints allows for checking out a program, but that only appears to create a lock and not actually download any program files. Is this still unsupported, or am I missing something?

[t0xk]

From my understanding this is still currently unsupported, i will look into it.

[bethington]

Confirming what @t0xk said: opening a server-checked-out program inside the headless container is currently not supported end-to-end. The /server/* endpoints handle auth, repo/folder listing, and checkout (which acquires the server-side lock and downloads the file to the local project cache), but the actual program-load path in headless mode does not yet bridge to the server-managed DomainFile and hand a Program to the rest of the service layer.

The GUI plugin (FrontEnd mode) does support this end-to-end via FrontEndProgramProvider opening on-demand from a DomainFile. So if you have a desktop Ghidra connected to your server, the MCP plugin will let an agent open, edit, save, and check in shared-server programs.

I'll re-scope #33's promise of POST /program/open-shared for the headless path as a tracked item — it's the right shape, the plumbing just hasn't been finished. Happy to take a PR if you want to take a swing at it; otherwise it'll land in a future release.

[bethington]

Update for everyone landing here — partial progress in v5.10.x.

After digging into this, the root cause is that /server/version_control/checkout operates on a standalone GhidraServerManager.RepositoryAdapter connection that lives independently of any open project. The checkout acquires the server-side lock, but content only flows to a local project if that local project is a shared project (one that was created bound to the server repo at creation time). A plain analyzeHeadless -import or GhidraProject.createProject produces a standalone project that won't see anything from /server/version_control/checkout.

What you need for the workflow to work today

The local project mounted into the headless container must be a shared project bound to the same server repository. Two ways to create one:

# Option A — Ghidra GUI, one-time setup
File → New Project → Shared Project → connect to ghidra://host:port → choose repo
# Save the resulting .gpr + project directory; mount both into the container

# Option B — analyzeHeadless from a workstation with Ghidra
analyzeHeadless /local/projectsdir MySharedProject \
    -connect ghidra://host:port/repo-name -user <user>
# Then mount /local/projectsdir into the container

Once that shared project is mounted at /data/projects/MyProject, the API flow is:

1. /open_project           { "path": "/data/projects/MyProject" }
2. /server/connect         (uses env GHIDRA_SERVER_HOST/PORT/USER/PASSWORD)
3. /get_project_info       → confirm  "project_server_bound": true
4. /server/version_control/checkout  { ... }     # optional — for writes
5. /load_program_from_project  { "path": "/Vanilla/1.13d/D2Common.dll" }

Step 3 is the critical sanity check that the v5.10.x changes now make easy.

What v5.10.x just shipped to make the failure mode obvious

Two diagnostic improvements on main (live after next plugin redeploy):

/get_project_info now surfaces server binding —

{
  "has_project": true,
  "project_name": "diablo2",
  "file_count": 577,
  "program_count": 577,
  "project_server_bound": true,
  "server": "10.0.10.30:13100",
  "server_repo": "diablo2"
}

If project_server_bound is false, your open project is local-only and /server/version_control/checkout won't deliver content /load_program_from_project can pick up — that's the diagnostic answer to "I checked out but can't open."

/load_program_from_project returns structured diagnostics on failure —

{
  "success": false,
  "error": "Program not found in project: /Vanilla/1.13d/D2Common.dll (project contains 0 program file(s))",
  "requested_path": "/Vanilla/1.13d/D2Common.dll",
  "diagnostics": {
    "project_open": true,
    "project_name": "fresh_local_project",
    "project_server_bound": false,
    "available_program_paths": [],
    "suggestion": "Project is local-only (not bound to a Ghidra Server). If you intended a server-checked-out file, the local project must be a shared project — create one via Ghidra GUI or `analyzeHeadless -connect ghidra://host:port/repo` and mount it into this container, then reopen it via /open_project."
  }
}

When the project IS shared but the path is wrong, the failure includes a preview of what's actually in the project so you can correct the path without dumping the whole tree:

{
  "diagnostics": {
    "project_server_bound": true,
    "server": "10.0.10.30:13100",
    "server_repo": "diablo2",
    "available_program_paths": [
      "/Vanilla/1.00/D2Client.dll",
      "/Vanilla/1.00/D2Common.dll",
      "/Vanilla/1.13d/D2Client.dll",
      "/Vanilla/1.13d/D2Common.dll",
      ...
    ]
  }
}

Still on the deck

The real fix that closes #119 fully is an endpoint that creates a shared-bound local project on demand without requiring an out-of-container setup step. That's still tracked here — it needs DefaultProjectManager.createProject(locator, repository, isShared=true) plumbing and a thorough cleanup story for the project lifecycle. Reopening as soon as that lands; the v5.10.x diagnostics above are scaffolding.

@j4s0n @t0xk — if you redeploy v5.10.x after merge and run the four-step sequence above, /get_project_info should make it obvious in 30 seconds whether the issue is project-binding or path-typo. Either way the next failure has actionable text instead of "Program not found." Let me know what the response looks like for your setup.