---
title: Quick start
description: Create an account, add an SSH key, and push your first repository to Tangled.
---


## Login or sign up

You can [login](https://tangled.org) by using your AT Protocol
account. If you are unclear on what that means, simply head
to the [signup](https://tangled.org/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:

```bash
ssh-keygen -t ed25519 -C "foo@bar.com"
```

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

Copy your public key to your clipboard:

```bash
# 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:

1. Hit the green `+` icon on the topbar, and select
   repository
2. Enter a repository name
3. Add a description
4. Choose a knotserver to host this repository on
5. 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](/knots/self-hosting/) 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](/knots/self-hosting/) section.

## Push your first repository

Initialize a new Git repository:

```bash
mkdir my-project
cd my-project

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

Add some content and push!

```bash
git add README.md
git commit -m "Initial commit"
git remote add origin git@tangled.org: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](#create-a-repository).

Navigate to your existing local repository:

```bash
cd /path/to/your/existing/repo
```

You can inspect your existing Git remote like so:

```bash
git remote -v
```

You'll see something like:

```bash
origin  git@github.com:username/my-project.git (fetch)
origin  git@github.com:username/my-project.git (push)
```

Update the remote URL to point to tangled:

```bash
git remote set-url origin git@tangled.org:user.tngl.sh/my-project
```

Verify the change:

```bash
git remote -v
```

You should now see:

```bash
origin  git@tangled.org:user.tngl.sh/my-project (fetch)
origin  git@tangled.org:user.tngl.sh/my-project (push)
```

Push all your branches and tags to Tangled:

```bash
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](https://git-scm.com/docs/git-push#_remotes).

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

```bash
$ git remote -v
origin  git@github.com:username/my-project.git (fetch)
origin  git@github.com:username/my-project.git (push)
```

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

```bash
git remote set-url --add --push origin git@tangled.org: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):

```bash
git remote set-url --add --push origin git@github.com:username/my-project.git
```

Verify your configuration:

```bash
$ git remote -v
origin  git@github.com:username/my-project.git (fetch)
origin  git@tangled.org:user.tngl.sh/my-project (push)
origin  git@github.com: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:

```bash
git push origin main
```

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

To push all branches and tags:

```bash
git push origin --all
git push origin --tags
```

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

```bash
git remote add github git@github.com:username/my-project.git
git remote add tangled git@tangled.org:user.tngl.sh/my-project
```

Then push to each explicitly:

```bash
git push github main
git push tangled main
```
