The longer guide to installing Crush with Deepseek
🚨🚨PSA: because this is getting some interest, please be careful when using Crush (or any agentic AI):
Crush is powered by the LLM of your choice and gets read and write permissions on your system when using it. It can view files and edit their content, or even delete them.
Mash the Esc key to instantly stop the AI if it's doing something it shouldn't, then ctrl+c to quit crush entirely - this severs the connection to the API and stops it outright.
Make a new folder for each project - this is its containment zone, it should never have to edit anything outside this folder. A project might be, "get the top AI articles of the week from arstechnica then write a summary of their three main points to summary.txt". You know how folders work.
Sometimes it may look outside of the folder if the task requires it (e.g. if you ask "do I have python installed"). Looking ought to be fine (your call), but don't let it edit stuff outside of your project folder blindly.
Install git (easy to install if you google for it), and use it - or make crush use it. 'git init' then 'git add .' then 'git commit -m "initial commit"' in your terminal. That way if anything gets deleted or broken inside the project's folder, you can revert to a previous commit that worked.
Only use 'Allow' when it requests a permission. This makes it so that every new command must be allowed to be run the first time in the session. Also review them and google them if you need to, don't just say yes.
Ctrl+N inside crush to create a new session and reset permissions you've granted.
Ultimately it's like any other computer software, it can bonk your computer if you don't know how to use it. It's very safe due to how sessions work, but not 110% safe. I could tell crush at any moment to "delete system32" and it would do it - it's a computer program, it does what you tell it to.
I see there's a lot of interest in using Crush/Deepseek API, so I'll try to write a longer guide to walk you through it. I'll also be adding pictures slowly so look out for that.
But to be honest, at this time the best thing you can do is go on https://chat.deepseek.com/ and ask it to write a guide for you, ordered step by step. When you run into a bug or issue send it the log and let it figure it out. Painless install!
Step 0: Difference between Deepseek Web and Deepseek API. And what's crush anyway?
I think it's important to understand the differences and what you are going to be doing. You can access Deepseek on the web at chat.deepseek.com. Deepseek web is completely free, and runs their latest models (v3 and r1 if you turn on thinking mode). They will never ask for your credit card.
The web interface has some limitations however. For example, it follows the User -> Assistant -> Stop model. You send a prompt, the assistant (that's deepseek) replies, and it stops until you repeat with another prompt. It also follows a rigid system prompt. The system prompt is a set of instructions the deepseek devs passed on to deepseek before it makes its answer, and it follows it. If you ever got hit with the "Sorry, that's beyond my current scope" - that's not the AI actually refusing to answer, that's an additional script analyzing keywords in the AI's response and replacing its message with that.
APIs have existed for quite a while and they basically allow you to communicate with a web service in the way its owners let you.
In my experience, API access for LLMs is less restrictive. I asked the famous lib questions over crush (which connects to the deepseek API) and it answered just fine without self-censoring. The second benefit of using the API is that it allows you to use it in any program of your choosing. Basically, it connects to your program and the LLM processes the query then returns an output. You can do a lot of things with this (like crush does) without being limited by the User -> Assistant -> Stop cycle of the web interface.
However, the API costs money to use. you can see the current pricing here: https://api-docs.deepseek.com/quick_start/pricing. It's cheap - I put 5$ in it a few months ago and haven't finished them yet despite using hundreds of millions of tokens.
What crush does is it connects over API and provides agentic capabilities to the LLM, which is wholly different from the web interface. Let's look at it in the next step:
Step 1: So what's an agent?
Sorry for more theory but you know how we communists are.
So the web interface follows a simple U-A-S cycle (as detailed above). It also can't access your computer's files to do stuff on, such as read or write to them.
But an agent can. And this is precisely what crush does. It tells the LLM "so if y'all want to read a document you just holler the [read:$file] command y'hear?" and the LLM does exactly this, and the agent interprets that and runs the command to read the document. You can simulate this on the web interface:
But of course on the web interface, this doesn't do anything because it's just text. The agent however interprets this text (to my understanding), and runs the appropriate commands on your system. It detects when the command was issued and runs it for the LLM. We are essentially tricking an LLM into having agency, thus agentic AI.
The agent has several tools it exposes to the LLM, such as web search, read, write, running terminal commands, etc. Here is an example of crush working on a task:
Then, I can ask it to write that synthesis down to a file which it will put on my computer. Here is what it synthesized for me btw (just for the example if you're curious): https://pastebin.com/tx0FnWwB
What's also very interesting with agentic work is it can prompt the LLM further by itself. This means that if the LLM gets stuck on a problem, for example a command that did not return a result, it can debug it itself: it will try another command automatically without you having to tell it to, until it finds a solution or a workaround.
The point of an agent is to work with you, not against you. It's like having your own dev by your side and you talk to it like you would a human dev. You'd be surprised what you can get it do to by just throwing a problem at it. Agentic work reduces friction because you just give it a task and it figures it out itself. If the LLM can't access a page with Fetch, it will try to find another way to access its contents. You just let it run.
Step 2: Installing crush
Honestly the installation is pretty painless. They have instructions here: https://github.com/charmbracelet/crush?tab=readme-ov-file#installation (this is their official repo). Select the instructions for your operating system and follow them - it's either typing a command in the shell (e.g. cmd on windows) or installing an .exe/.deb package (I myself being on an ubuntu fork I recommend the deb, it sets everything up to receive updates).
Important: once crush has finished installing inside the terminal, quit that terminal window and open a new one to refresh it.
Once it's installed, you need to create a folder somewhere on your machine: this will be where crush works. Anywhere you like is fine. It should never be able to leave this folder, but sometimes it can. I make a new folder for each project.
using the shell (cmd on windows), navigate to your folder with: cd /path/. Then simply type the 'crush' command, and it will set up what it needs to the first time. In the meantime, go on to step 3 - don't touch anything in crush.
On the left, go into Top Up and top up your API with your credit card. Like I said 5$ gets you very far, or they offer 2$ to start with. To give you an idea I put 5$ in a few months ago, sent and received hundreds of millions of tokens, and I still haven't used up all of that credit.
Go into API Keys, create a new API key, give it a name,
Click next and copy that key. Warning: they will never show you that API key once you close that modal window, but you can delete it and create new ones. also you should never show anyone else your API keys, they're like a password. With your key, anyone could use your deepseek credit instead of you.
Step 4: Connecting the API key to crush
Go back to your crush interface in the terminal. On first boot iirc it will ask you which LLM you want to connect to. Type "Thinking mode" to find Deepseek -- there's a bunch of different providers installed by default that also have Deepseek, we want the official one. Select that with the arrow keys and press enter:
It will ask for your API key, simply press Ctrl+Shift+V to paste the API key you got from platform.deepseek.com, then Enter.
If it works, simply send 'hello!' once you have access to the chat: if you get a response, you're connected!
Happy prompting.
Step 5: How to use crush
To go beyond look for guides in this community! And please heed the PSA at the top of this guide.
lmk if you have any questions or something glitched but it should pretty much work by itself.
CriticalResist8 in crushagent
The longer guide to installing Crush with Deepseek
🚨🚨PSA: because this is getting some interest, please be careful when using Crush (or any agentic AI):
Ultimately it's like any other computer software, it can bonk your computer if you don't know how to use it. It's very safe due to how sessions work, but not 110% safe. I could tell crush at any moment to "delete system32" and it would do it - it's a computer program, it does what you tell it to.
I see there's a lot of interest in using Crush/Deepseek API, so I'll try to write a longer guide to walk you through it. I'll also be adding pictures slowly so look out for that.
But to be honest, at this time the best thing you can do is go on https://chat.deepseek.com/ and ask it to write a guide for you, ordered step by step. When you run into a bug or issue send it the log and let it figure it out. Painless install!
Step 0: Difference between Deepseek Web and Deepseek API. And what's crush anyway?
I think it's important to understand the differences and what you are going to be doing. You can access Deepseek on the web at chat.deepseek.com. Deepseek web is completely free, and runs their latest models (v3 and r1 if you turn on thinking mode). They will never ask for your credit card.
The web interface has some limitations however. For example, it follows the User -> Assistant -> Stop model. You send a prompt, the assistant (that's deepseek) replies, and it stops until you repeat with another prompt. It also follows a rigid system prompt. The system prompt is a set of instructions the deepseek devs passed on to deepseek before it makes its answer, and it follows it. If you ever got hit with the "Sorry, that's beyond my current scope" - that's not the AI actually refusing to answer, that's an additional script analyzing keywords in the AI's response and replacing its message with that.
APIs have existed for quite a while and they basically allow you to communicate with a web service in the way its owners let you.
In my experience, API access for LLMs is less restrictive. I asked the famous lib questions over crush (which connects to the deepseek API) and it answered just fine without self-censoring. The second benefit of using the API is that it allows you to use it in any program of your choosing. Basically, it connects to your program and the LLM processes the query then returns an output. You can do a lot of things with this (like crush does) without being limited by the User -> Assistant -> Stop cycle of the web interface.
However, the API costs money to use. you can see the current pricing here: https://api-docs.deepseek.com/quick_start/pricing. It's cheap - I put 5$ in it a few months ago and haven't finished them yet despite using hundreds of millions of tokens.
What crush does is it connects over API and provides agentic capabilities to the LLM, which is wholly different from the web interface. Let's look at it in the next step:
Step 1: So what's an agent?
Sorry for more theory but you know how we communists are.
So the web interface follows a simple U-A-S cycle (as detailed above). It also can't access your computer's files to do stuff on, such as read or write to them.
But an agent can. And this is precisely what crush does. It tells the LLM "so if y'all want to read a document you just holler the [read:$file] command y'hear?" and the LLM does exactly this, and the agent interprets that and runs the command to read the document. You can simulate this on the web interface:
But of course on the web interface, this doesn't do anything because it's just text. The agent however interprets this text (to my understanding), and runs the appropriate commands on your system. It detects when the command was issued and runs it for the LLM. We are essentially tricking an LLM into having agency, thus agentic AI.
The agent has several tools it exposes to the LLM, such as web search, read, write, running terminal commands, etc. Here is an example of crush working on a task:
Then, I can ask it to write that synthesis down to a file which it will put on my computer. Here is what it synthesized for me btw (just for the example if you're curious): https://pastebin.com/tx0FnWwB
What's also very interesting with agentic work is it can prompt the LLM further by itself. This means that if the LLM gets stuck on a problem, for example a command that did not return a result, it can debug it itself: it will try another command automatically without you having to tell it to, until it finds a solution or a workaround.
The point of an agent is to work with you, not against you. It's like having your own dev by your side and you talk to it like you would a human dev. You'd be surprised what you can get it do to by just throwing a problem at it. Agentic work reduces friction because you just give it a task and it figures it out itself. If the LLM can't access a page with Fetch, it will try to find another way to access its contents. You just let it run.
Step 2: Installing crush
Honestly the installation is pretty painless. They have instructions here: https://github.com/charmbracelet/crush?tab=readme-ov-file#installation (this is their official repo). Select the instructions for your operating system and follow them - it's either typing a command in the shell (e.g. cmd on windows) or installing an .exe/.deb package (I myself being on an ubuntu fork I recommend the deb, it sets everything up to receive updates).
Important: once crush has finished installing inside the terminal, quit that terminal window and open a new one to refresh it.
Once it's installed, you need to create a folder somewhere on your machine: this will be where crush works. Anywhere you like is fine. It should never be able to leave this folder, but sometimes it can. I make a new folder for each project.
using the shell (cmd on windows), navigate to your folder with: cd /path/. Then simply type the 'crush' command, and it will set up what it needs to the first time. In the meantime, go on to step 3 - don't touch anything in crush.
Step 3: Setting up your deepseek API key
Go on https://platform.deepseek.com/ and log in with your deepseek account (same as the web interface).
On the left, go into Top Up and top up your API with your credit card. Like I said 5$ gets you very far, or they offer 2$ to start with. To give you an idea I put 5$ in a few months ago, sent and received hundreds of millions of tokens, and I still haven't used up all of that credit.
Step 4: Connecting the API key to crush
Go back to your crush interface in the terminal. On first boot iirc it will ask you which LLM you want to connect to. Type "Thinking mode" to find Deepseek -- there's a bunch of different providers installed by default that also have Deepseek, we want the official one. Select that with the arrow keys and press enter:
It will ask for your API key, simply press Ctrl+Shift+V to paste the API key you got from platform.deepseek.com, then Enter.
If it works, simply send 'hello!' once you have access to the chat: if you get a response, you're connected!
Happy prompting.
Step 5: How to use crush
To go beyond look for guides in this community! And please heed the PSA at the top of this guide.
lmk if you have any questions or something glitched but it should pretty much work by itself.