Skip to main content

gitd-client for Python

A client for gitd: instant, secretless git checkouts for agent sandboxes. Your agents work in their own copy and publish a branch; they never see your token.

pip install gitd-client

It is imported as gitd. Up to 0.13.0 it was published as gitd; from 0.14.0 it is gitd-client, the name every gitd client has.

from gitd import Gitd, GitdError

with Gitd() as gitd:                      # $GITD_SOCKET, then /run/gitd/gitd.sock
    workspace = gitd.prepare("https://github.com/acme/web", "/var/lib/gitd/workspaces/agent-1")
    print(workspace.path, workspace.commit, workspace.strategy)

    # … the agent works in workspace.path with plain git, and commits …

    published = gitd.publish(workspace.path, "agents/fix-login")
    gitd.remove(workspace.path)

No call takes a credential: gitd reads and publishes with the ones it keeps.

Method What it does
prepare(url, path, *, branch, commit, submodules, full_history, strategy, warm, new_branch, on_progress) A workspace of a repository at a path under gitd's roots, on a new branch of its own with new_branch
update(path, *, branch, merge, submodules, on_progress) To the tip of its branch, or of the branch given; with merge, that branch merged into the one it is on
checkout(path, commit, *, submodules, on_progress) To a commit, as a rollback does
describe(path) Its repository, commit, branch, uncommitted changes and submodules
publish(path, branch=None, *, requested_by, pull_request, provenance, sandbox, update) Its commits pushed to a new branch, or to the branch it is on when none is given; with update, or a branch it published before, that branch moved forward; its pull request opened or updated
remove(path) Deleted; its pool stays
list() Every workspace gitd made, described, with the branches published from each
probe(url) Whether it can be read, its default branch and branches
info() Which gitd answers, and how it makes workspaces here and why
audit(*, since, url, limit) Every publish, done or refused, newest first
from gitd import PullRequestOptions

published = gitd.publish(
    workspace.path, "agents/fix-login", update=True,
    pull_request=PullRequestOptions(open=True, submodules=True, title="Fix the login", body="…"),
)
print(published.pull_request.url, published.pull_request.updated)
for submodule in published.submodule_pull_requests:   # merged first, with a merge commit
    print(submodule.path, submodule.pull_request or submodule.refused)

A refusal raises GitdError, with reason (AUTH_REQUIRED, NOT_FOUND, PATH_REFUSED, BRANCH_REFUSED, BUSY, …) and said, what git said. Decide from the reason, never from the message.

examples/agent.py is an agent's whole round trip.

Layout

Path What it is
src/gitd/client.py Gitd, the client
src/gitd/models.py What gitd answers, as dataclasses
src/gitd/errors.py GitdError
src/gitd/timestamps.py Between the contract's timestamps and datetime
src/gitd/connection.py The channel to the socket, and how calls are made
src/gitd/methods.py The gitd methods called, by their gRPC path
src/gitd/messages.py The messages of the contract the client uses
src/gitd/contract.py Reads the contract at run time, with protobuf's public API
src/gitd/contract.json The contract, built from proto/gitd/v1/gitd.proto by make generate

No code is generated: the client reads gitd's contract when it starts.

Python 3.11 or later, on Linux, macOS and Windows. Apache-2.0.

Metadata

Release files for gitd-client 0.15.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gitd-client 0.15.0
File Size Uploaded Provenance Actions
gitd_client-0.15.0.tar.gz 26.8 kB With provenance Details for gitd_client-0.15.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gitd-client 0.15.0
File Interpreter ABI Platform Actions
gitd_client-0.15.0-py3-none-any.whl Python 3 none any Details for gitd_client-0.15.0-py3-none-any.whl

Total release size: 60.0 kB

Release files / gitd_client-0.15.0.tar.gz

Download URL gitd_client-0.15.0.tar.gz
Size 26.8 kB
Tags Source
SHA-256 checksum
How to use checksums
49fed274ef9b8e06893ca3a81ecf94843a73d6da1f640f5806167ded34734a75
BLAKE2b-256 checksum
How to use checksums
fafa6606c489412a761ebba97e76fd800f2e4beaf4204924ebfe9a4e9a2812a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / gitd_client-0.15.0-py3-none-any.whl

Download URL gitd_client-0.15.0-py3-none-any.whl
Size 33.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d409fde8e553de1a3b5920fcd8bc70125e55259f1f3640dce21f5aa706be552c
BLAKE2b-256 checksum
How to use checksums
dfb2a45e0affc432fc5287ba594df65c16671a06d7d7ccd8e5386d3124c99d68
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for gitd-client 0.15.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for gitd_client-0.15.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page