Quick start guide

You can login by using your AT Protocol account. If you are unclear on what that means, simply head to the signup page and create an account. By doing so, you will be choosing Tangled as your account provider (you will be granted a handle of the form user.tngl.sh).

In the AT Protocol network, users are free to choose their account provider (known as a “Personal Data Service”, or PDS), and login to applications that support AT accounts.

You can think of it as “one account for all of the atmosphere”!

If you already have an AT account (you may have one if you signed up to Bluesky, for example), you can login with the same handle on Tangled (so just use user.bsky.social on the login page).

Add an SSH key

Once you are logged in, you can start creating repositories and pushing code. Tangled supports pushing git repositories over SSH.

First, you’ll need to generate an SSH key if you don’t already have one:

ssh-keygen -t ed25519 -C "[email protected]"

When prompted, save the key to the default location (~/.ssh/id_ed25519) and optionally set a passphrase.

Copy your public key to your clipboard:

# on X11
cat ~/.ssh/id_ed25519.pub | xclip -sel c

# on wayland
cat ~/.ssh/id_ed25519.pub | wl-copy

# on macos
cat ~/.ssh/id_ed25519.pub | pbcopy

Now, navigate to ‘Settings’ -> ‘Keys’ and hit ‘Add Key’, paste your public key, give it a descriptive name, and hit save.

Create a repository

Once your SSH key is added, create your first repository:

Hit the green + icon on the topbar, and select repository
Enter a repository name
Add a description
Choose a knotserver to host this repository on
Hit create

Knots are self-hostable, lightweight Git servers that can host your repository. Unlike traditional code forges, your code can live on any server. Read the Knots section for more.

Configure SSH

To ensure Git uses the correct SSH key and connects smoothly to Tangled, add this configuration to your ~/.ssh/config file:

Host tangled.org
    Hostname tangled.org
    User git
    IdentityFile ~/.ssh/id_ed25519
    AddressFamily inet

This tells SSH to use your specific key when connecting to Tangled and prevents authentication issues if you have multiple SSH keys.

Note that this configuration only works for knotservers that are hosted by tangled.org. If you use a custom knot, refer to the Knots section.

Push your first repository

Initialize a new Git repository:

mkdir my-project
cd my-project

git init
echo "# My Project" > README.md

Add some content and push!

git add README.md
git commit -m "Initial commit"
git remote add origin [email protected]:user.tngl.sh/my-project
git push -u origin main

That’s it! Your code is now hosted on Tangled.

Migrating an existing repository

Moving your repositories from GitHub, GitLab, Bitbucket, or any other Git forge to Tangled is straightforward. You’ll simply change your repository’s remote URL. At the moment, Tangled does not have any tooling to migrate data such as GitHub issues or pull requests.

First, create a new repository on tangled.org as described in the Quick Start Guide.

Navigate to your existing local repository:

cd /path/to/your/existing/repo

You can inspect your existing Git remote like so:

git remote -v

You’ll see something like:

origin  [email protected]:username/my-project.git (fetch)
origin  [email protected]:username/my-project.git (push)

Update the remote URL to point to tangled:

git remote set-url origin [email protected]:user.tngl.sh/my-project

Verify the change:

git remote -v

You should now see:

origin  [email protected]:user.tngl.sh/my-project (fetch)
origin  [email protected]:user.tngl.sh/my-project (push)

Push all your branches and tags to Tangled:

git push -u origin --all
git push -u origin --tags

Your repository is now migrated to Tangled! All commit history, branches, and tags have been preserved.

Mirroring a repository to Tangled

If you want to maintain your repository on multiple forges simultaneously, for example, keeping your primary repository on GitHub while mirroring to Tangled for backup or redundancy, you can do so by adding multiple remotes.

You can configure your local repository to push to both Tangled and, say, GitHub. You may already have the following setup:

$ git remote -v
origin  [email protected]:username/my-project.git (fetch)
origin  [email protected]:username/my-project.git (push)

Now add Tangled as an additional push URL to the same remote:

git remote set-url --add --push origin [email protected]:user.tngl.sh/my-project

You also need to re-add the original URL as a push destination (Git will now use the original URL to fetch only):

git remote set-url --add --push origin [email protected]:username/my-project.git

Verify your configuration:

$ git remote -v
origin  [email protected]:username/my-project.git (fetch)
origin  [email protected]:user.tngl.sh/my-project (push)
origin  [email protected]:username/my-project.git (push)

Notice that there’s one fetch URL (the primary remote) and two push URLs. Now, whenever you push, Git will automatically push to both remotes:

git push origin main

This single command pushes your main branch to both GitHub and Tangled simultaneously.

To push all branches and tags:

git push origin --all
git push origin --tags

If you prefer more control over which remote you push to, you can maintain separate remotes:

git remote add github [email protected]:username/my-project.git
git remote add tangled [email protected]:user.tngl.sh/my-project

Then push to each explicitly:

git push github main
git push tangled main