Skip to content

Workspaces

A workspace is the local home for ComfyGit on one machine. It contains your environments, shared model index, registry cache, logs, and machine-specific configuration.

Most users should keep one workspace per machine. Environments inside that workspace are the portable units you commit, push, pull, import, export, and materialize.

Create A Workspace

Initialize the default workspace at ~/comfygit:

cg init

If you already have a ComfyUI model directory, point ComfyGit at it during initialization:

cg init --models-dir ~/ComfyUI/models --yes

You can also create a workspace at a custom path:

cg init /path/to/workspace --models-dir /path/to/models

When you use a custom path, set COMFYGIT_HOME before running other commands:

export COMFYGIT_HOME=/path/to/workspace

Add that export to your shell profile if this should be your normal workspace.

What Lives There

A typical workspace looks like this:

~/comfygit/
├── environments/
│   ├── deforum-testing/
│   └── production/
├── models/
│   ├── checkpoints/
│   ├── loras/
│   └── ...
├── comfygit_cache/
│   ├── model_index.db
│   ├── registry_cache.db
│   └── workflow_cache.db
├── logs/
└── .metadata/

The important distinction is portability:

  • Environment repositories contain the tracked pyproject.toml manifest.
  • Model bytes stay outside git and are resolved through hashes, sources, and paths.
  • Workspace metadata, logs, caches, local source overrides, and virtual environments are local runtime state.

This is why you can push an environment repo without pushing your whole machine state.

Inspect Configuration

Use cg config --show to see which workspace and shared settings are active:

cg config --show

The config output includes the workspace path and uv cache location. Provider authentication status is intentionally separate and never displays token suffixes:

cg auth status

Set optional credentials through a hidden prompt:

cg auth set civitai
cg auth set huggingface
cg auth set github

Hugging Face can also use its provider-native browser login:

cg auth login huggingface

Clear a workspace credential or migrate older plaintext workspace values:

cg auth clear civitai
cg auth migrate

Durable ComfyGit credentials are stored through the operating-system credential store. The CLI includes the optional keyring adapter, but a working OS backend is still required to save credentials. Headless machines can use provider environment variables or an existing Hugging Face login without configuring desktop keyring. ComfyGit does not silently write new credentials to plaintext files.

Resolution order is: an explicit Core API override, provider environment variables, workspace secure storage, provider-native login, then legacy workspace values during migration. An explicit API value of None disables credential discovery for that provider. Environment variables include CIVITAI_API_TOKEN (or CIVITAI_API_KEY), HF_TOKEN (or HUGGING_FACE_HUB_TOKEN), and GITHUB_TOKEN (or GH_TOKEN).

Core library consumers can install comfygit-core without keyring. Add comfygit-core[keyring] only when OS persistence is wanted, or supply your own CredentialStore. cg auth status identifies the source without printing tokens.

An external uv cache can reduce repeated downloads across environments:

cg config --uv-cache /path/to/uv-cache

Model Index

The workspace has one shared model index. It scans the configured models directory and records local paths, categories, filenames, sizes, and hashes.

Check the index:

cg model index status
cg model index list

Point the workspace at a different models directory:

cg model index dir /path/to/models

Rescan after adding files outside ComfyGit:

cg model index sync

The index is local. Workflow manifests decide which indexed models are required for a particular environment or workflow.

Registry Cache

ComfyGit uses the ComfyUI registry cache to resolve published custom nodes.

cg registry status
cg registry update

Update the registry when a recently published node cannot be found, or when you are preparing an environment for someone else to materialize.

Logs And Diagnostics

cg debug shows recent workspace or environment logs:

cg debug
cg debug -n 50
cg debug --level ERROR
cg debug --workspace

For orchestrator state and logs:

cg orch status
cg orch logs -n 100

Use these commands before deleting local state. Most sync, node install, model index, and manager update problems leave useful context in the logs.

Multiple Workspaces

Multiple workspaces are useful for hard isolation, but they add overhead. Prefer one workspace unless you have a specific reason to separate model directories, caches, or environment sets.

Switch workspaces by changing COMFYGIT_HOME:

export COMFYGIT_HOME=~/comfygit-work
cg list

export COMFYGIT_HOME=~/comfygit-personal
cg list

Each workspace has its own environment list, model index, cache, logs, and configuration.

Practical Rules

  • Put large model files in the shared models directory, not in environment git repos.
  • Commit environment changes from inside the environment with cg commit.
  • Use cg model index sync after manually adding models to the filesystem.
  • Use cg registry update when a node lookup looks stale.
  • Avoid editing .metadata files directly; use CLI commands instead.

Next Steps